OSQDel

Description

Deletes a message queue. This function should be used with care since multiple tasks may rely on the presence of the message queue. Generally speaking, before deleting a message queue, first delete all the tasks that can access the message queue. However, it is highly recommended that you do not delete kernel objects at run time.

Files

os.h/os_q.c

Prototype

OS_OBJ_QTY  OSQDel (OS_Q    *p_q,
                    OS_OPT   opt,
                    OS_ERR  *p_err)

Arguments

p_q

is a pointer to the message queue to delete.

opt

specifies whether to delete the queue only if there are no pending tasks (OS_OPT_DEL_NO_PEND), or always delete the queue regardless of whether tasks are pending or not (OS_OPT_DEL_ALWAYS). In this case, all pending task are readied.

p_err

is a pointer to a variable that is used to hold an error code. The error code can be one of the following:

OS_ERR_NONE

If the call is successful and the message queue has been deleted.

OS_ERR_DEL_ISR

If OS_CFG_CALLED_FROM_ISR_CHK_EN set to DEF_ENABLED in os_cfg.h: if the user attempts to delete the message queue from an ISR.

OS_ERR_ILLEGAL_DEL_RUN_TIME

If OS_SAFETY_CRITICAL_IEC61508 is defined: you called this after calling OSStart() and thus you are no longer allowed to delete kernel objects.

OS_ERR_OBJ_PTR_NULL

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

OS_ERR_OBJ_TYPE

If OS_CFG_OBJ_TYPE_CHK_EN is set to DEF_ENABLED in os_cfg.h: if p_q is not pointing to a queue.

OS_ERR_OPT_INVALID

If not specifying one of the two options mentioned in the opt argument.

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.

OS_ERR_TASK_WAITING

If one or more tasks are waiting for messages at the message queue and it is specified to only delete if no task is pending.

Returned Value

The number of tasks that were waiting on the message queue and 0 if an error is detected or if no tasks were waiting.

Required Configuration

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

Callers

Application.

Notes/Warnings

1. Message queues must be created before they can be used.
2. This function must be used with care. Tasks that would normally expect the presence of the queue must check the return code of OSQPend().

Example Usage

          OS_Q  DispQ;
           
           
          void Task (void *p_arg)
          {
              OS_ERR      err;
              OS_OBJ_QTY  qty;
           
           
              (void)&p_arg;
              while (DEF_ON) {
                  :
                  :
                  qty = OSQDel(&DispQ,
                                OS_OPT_DEL_ALWAYS,
                               &err);
                  /* Check "err" */
                  :
                  :
              }
          }