OSTaskQFlush

Description

OSTaskQFlush() empties the contents of the task message queue and eliminates all messages sent to the queue. OS_MSGs from the queue are simply returned to the free pool of OS_MSGs.

Files

os.h/os_task.c

Prototype

OS_MSG_QTY  OSTaskQFlush (OS_TCB  *p_tcb,
                          OS_ERR  *p_err)

Arguments

p_tcb

is a pointer to the TCB of the task that contains the queue to flush. Specifying a NULL pointer tells OSTaskQFlush() to flush the queue of the calling task’s built-in message queue.

p_err

is a pointer to a variable that will contain an error code returned by this function.

OS_ERR_NONE

If the message queue is flushed.

OS_ERR_FLUSH_ISR

If OS_CFG_CALLED_FROM_ISR_CHK_EN set to DEF_ENABLED in os_cfg.h: if calling this function from an ISR

OS_ERR_OS_NOT_RUNNING

If OS_CFG_INVALID_OS_CALLS_CHK_EN is set to DEF_ENABLED in os_cfg.h: if µC/OS-III is not running yet.

Returned Value

The number of OS_MSG entries freed from the message queue. Note that the OS_MSG entries are returned to the free pool of OS_MSGs.

Required Configuration

OS_CFG_TASK_Q_EN must be enabled in os_cfg.h. Refer to µC-OS-III Configuration Manual.

Callers

Application.

Notes/Warnings

1. Use this function with great care. When flushing a queue, you lose the references to what the queue entries are pointing to, potentially causing 'memory leaks'. The data that the user is pointing to that is referenced by the queue entries should, most likely, be de-allocated (i.e., freed).

Example Usage

          void Task (void *p_arg)
          {
              OS_ERR      err;
              OS_MSG_QTY  entries;
           
              (void)&p_arg;
              while (DEF_ON) {
                  :
                  :
                  entries = OSTaskQFlush((OS_TCB *)0,
                                         &err);
                  /* Check "err" */
                  :
                  :
              }
          }
    

or, to flush a queue that contains entries, instead you can use OSTaskQPend() and specify the OS_OPT_PEND_NON_BLOCKING option.

          void Task (void *p_arg)
          {
              OS_ERR       err;
              CPU_TS       ts;
              OS_MSG_SIZE  msg_size;
           
           
              (void)&p_arg;
              :
              do {
                  OSTaskQPend(0,
                              OS_OPT_PEND_NON_BLOCKING,
                             &msg_size,
                             &ts,
                             &err);
              } while (err != OS_ERR_PEND_WOULD_BLOCK);
              :
              :
          }