OSTaskQPend

Description

OSTaskQPend() allows a task to receive messages directly from an ISR or another task, without going through an intermediate message queue. In fact, each task has a built-in message queue if the configuration constant OS_CFG_TASK_Q_EN is set to DEF_ENABLED. The messages received are pointer-sized variables, and their use is application specific. If at least one message is already present in the message queue when OSTaskQPend() is called, the message is retrieved and returned to the caller.

If no message is present in the task’s message queue and OS_OPT_PEND_BLOCKING is specified for the opt argument, OSTaskQPend() suspends the current task (assuming the scheduler is not locked) until either a message is received, or a user-specified timeout expires. A pended task that is suspended with OSTaskSuspend() can receive messages. However, the task remains suspended until it is resumed by calling OSTaskResume().

If no message is present in the task’s message queue and OS_OPT_PEND_NON_BLOCKING is specified for the opt argument, OSTaskQPend() returns to the caller with an appropriate error code and returns a NULL pointer.

Files

os.h/os_task.c

Prototype

void  *OSTaskQPend (OS_TICK       timeout,
                    OS_OPT        opt,
                    OS_MSG_SIZE  *p_msg_size,
                    CPU_TS       *p_ts,
                    OS_ERR       *p_err)

Arguments

timeout

allows the task to resume execution if a message is not received from a task or an ISR within the specified number of clock ticks. A timeout value of 0 indicates that the task wants to wait forever for a message. The timeout value is not synchronized with the clock tick. The timeout count starts decrementing on the next clock tick, which could potentially occur immediately.

opt

determines whether or not the user wants to block if a message is not available in the task’s queue. This argument must be set to either:

OS_OPT_PEND_BLOCKING, or
OS_OPT_PEND_NON_BLOCKING

Note that the timeout argument should be set to 0 when OS_OPT_PEND_NON_BLOCKING is specified, since the timeout value is irrelevant using this option.

p_msg_size

is a pointer to a variable that will receive the size of the message.

p_ts

is a pointer to a timestamp indicating when the task’s queue was posted, or the pend aborted. Passing a NULL pointer is valid and indicates that the timestamp is not necessary.

A timestamp is useful when the task must know when the task message queue was posted, or how long it took for the task to resume after the task message queue was posted. In the latter case, call OS_TS_GET() and compute the difference between the current value of the timestamp and *p_ts. In other words:

delta = OS_TS_GET() - *p_ts;

p_err

is a pointer to a variable used to hold an error code.

OS_ERR_NONE

If a message is received.

OS_ERR_OPT_INVALID

If OS_CFG_ARG_CHK_EN set to DEF_ENABLED in os_cfg.h: if you specified an invalid option.

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_PEND_ABORT

If the pend was aborted because another task called OSTaskQPendAbort().

OS_ERR_PEND_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_PEND_WOULD_BLOCK

If calling this function with the opt argument set to OS_OPT_PEND_NON_BLOCKING and no message is in the task’s message queue.

OS_ERR_PTR_INVALID

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

OS_ERR_SCHED_LOCKED

If calling this function when the scheduler is locked and the user wanted to block.

OS_ERR_TIMEOUT

If a message is not received within the specified timeout.

Returned Value

The message if no error or a NULL pointer upon error. You should examine the error code since it is possible to send NULL pointer messages. In other words, a NULL pointer does not mean an error occurred. *p_err must be examined to determine the reason for the error.

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. Do not call OSTaskQPend() from an ISR.

Example Usage

          void  CommTask (void *p_arg)
          {
              OS_ERR        err;
              void         *p_msg;
              OS_MSG_SIZE   msg_size;
              CPU_TS        ts;
           
           
              (void)&p_arg;
              while (DEF_ON) {
                  :
                  :
                  p_msg = OSTaskQPend(100,
                                      OS_OPT_PEND_BLOCKING,
                                      &msg_size,
                                      &ts,
                                      &err);
                  /* Check "err" */
                  :
                  :
              }
          }