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
, orOS_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
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" */ : : } }