OSQPend

Description

Used when a task wants to receive messages from a message queue. The messages are sent to the task via the message queue either by an ISR, or by another task using the OSQPost() call. 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 OSQPend() is called, the message is retrieved and returned to the caller.

If no message is present in the message queue and OS_OPT_PEND_BLOCKING is specified for the opt argument, OSQPend() suspends the current task until either a message is received, or a user-specified timeout expires. If a message is sent to the message queue and multiple tasks are waiting for such a message, µC/OS-III resumes the highest priority task that is waiting.

A pended task suspended with OSTaskSuspend() can receive a message. However, the task remains suspended until it is resumed by calling OSTaskResume().

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

Files

os.h/os_q.c

Prototype

void  *OSQPend (OS_Q         *p_q,
                OS_TICK       timeout,
                OS_OPT        opt,
                OS_MSG_SIZE  *p_msg_size,
                CPU_TS       *p_ts,
                OS_ERR       *p_err)

Arguments

p_q

is a pointer to the queue from which the messages are received.

timeout

allows the task to resume execution if a message is not received from the message queue within the specified number of clock ticks. A timeout value of 0 indicates that the task is willing 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 to block if a message is not available in the 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 specifying OS_OPT_PEND_NON_BLOCKING, 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 (in number of bytes).

p_ts

is a pointer to a variable that will receive the timestamp of when the message was received. Passing a NULL pointer is valid, and indicates that the user does not need the timestamp.

A timestamp is useful when the user wants the task to know when the message queue was posted, or how long it took for the task to resume after the message queue was posted. In the latter case, you would 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_OBJ_DEL

If the message queue was deleted.

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 p_q is not pointing to a message queue.

OS_ERR_OPT_INVALID

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if you specified invalid options.

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 OSQPendAbort().

OS_ERR_PEND_ISR

If OS_CFG_CALLED_FROM_ISR_CHK_EN set to DEF_ENABLED in os_cfg.h: if the function is called from an ISR.

OS_ERR_PEND_WOULD_BLOCK

If this function is called with the opt argument set to OS_OPT_PEND_NON_BLOCKING, and no message is in the queue.

OS_ERR_PTR_INVALID

If OS_CFG_ARG_CHK_EN is 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.

OS_ERR_TIMEOUT

If a message is not received within the specified timeout.

Returned Value

The message (i.e., a pointer) or a NULL pointer if no messages has been received. Note that it is possible for the actual message to be a NULL pointer, so you should check the returned error code instead of relying on the returned value.

Required Configuration

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

Callers

Application.

Notes/Warnings

Queues must be created before they are used.

Example Usage

OSQPend() example usage

          OS_Q  CommQ;
           
           
          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 = OSQPend(&CommQ,
                                   100,
                                   OS_OPT_PEND_BLOCKING,
                                  &msg_size,
                                  &ts,
                                  &err);
                  /* Check "err" */
                  :
                  :
              }
          }

µC/OS-III Documentation