OSQFlush

Description

Empties the contents of the message queue and eliminates all messages sent to the queue. This function takes the same amount of time to execute regardless of whether tasks are waiting on the queue (and thus no messages are present), or the queue contains one or more messages. OS_MSGs from the queue are simply returned to the free pool of OS_MSGs.

Files

os.h/os_q.c

Prototype

OS_MSG_QTY  OSQFlush (OS_Q    *p_q,
                      OS_ERR  *p_err)

Arguments

p_q

is a pointer to the 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_OBJ_PTR_NULL

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if p_q is a NULL pointer.

OS_ERR_OBJ_TYPE

If OS_CFG_OBJ_TYPE_CHK_EN is set to DEF_ENABLED in os_cfg.h: if you attempt to flush an object other than a message queue.

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_Q_EN and OS_CFG_Q_FLUSH_EN must be enabled in os_cfg.h. Refer to µC-OS-III Configuration Manual.

Callers

Application.

Notes/Warnings

1. Queues must be created before they are used.
2. 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

          OS_Q  CommQ;
           
           
          void Task (void *p_arg)
          {
              OS_ERR      err;
              OS_MSG_QTY  entries;
           
              (void)&p_arg;
              while (DEF_ON) {
                  :
                  :
                  entries = OSQFlush(&CommQ,
                                     &err);
                  /* Check "err" */
                  :
                  :
              }
          }

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

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