OSQPost

Description

Sends a message to a task through a message queue. A message is a pointer-sized variable, and its use is application specific. If the message queue is full, an error code is returned to the caller. In this case, OSQPost() immediately returns to its caller, and the message is not placed in the message queue.

If any task is waiting for a message to be posted to the message queue, the highest-priority task receives the message. If the task waiting for the message has a higher priority than the task sending the message, the higher-priority task resumes, and the task sending the message is suspended; that is, a context switch occurs. Message queues can be first-in first-out (OS_OPT_POST_FIFO), or last-in-first-out (OS_OPT_POST_LIFO) depending of the value specified in the opt argument.

If any task is waiting for a message at the message queue, OSQPost() allows the user to either post the message to the highest-priority task waiting at the queue (opt set to OS_OPT_POST_FIFO or OS_OPT_POST_LIFO), or to all tasks waiting at the message queue (opt is set to OS_OPT_POST_ALL). In either case, scheduling occurs unless opt is also set to OS_OPT_POST_NO_SCHED.

Files

os.h/os_q.c

Prototype

void  OSQPost (OS_Q         *p_q,
               void         *p_void,
               OS_MSG_SIZE   msg_size,
               OS_OPT        opt,
               OS_ERR       *p_err)

Arguments

p_q

is a pointer to the message queue being posted to.

p_void

is the actual message posted. p_void is a pointer-sized variable. Its meaning is application specific.

msg_size

specifies the size of the message (in number of bytes).

opt

determines the type of POST performed. The last two options may be added to either OS_OPT_POST_FIFO or OS_OPT_POST_LIFO to create different combinations:

OS_OPT_POST_FIFO

POST message to the end of the queue (FIFO), or send message to a single waiting task.

OS_OPT_POST_LIFO

POST message to the front of the queue (LIFO), or send message to a single waiting task

OS_OPT_POST_ALL

POST message to ALL tasks that are waiting on the queue. This option can be added to either OS_OPT_POST_FIFO or OS_OPT_POST_LIFO.

OS_OPT_POST_NO_SCHED

This option specifies to not call the scheduler after the post and therefore the caller is resumed, even if the message was posted to a message queue with tasks having a higher priority than the caller.

You would use this option if the task (or ISR) calling OSQPost() will do additional posts, in this case, the caller does not want to reschedule until finished, and, multiple posts are to take effect simultaneously.

p_err

is a pointer to a variable that will contain an error code returned by this function.

OS_ERR_NONE

If no tasks were waiting on the queue. In this case, the return value is also 0.

OS_ERR_MSG_POOL_EMPTY

If there are no more OS_MSG structures to use to store the message.

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 a valid option is not specified.

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_Q_MAX

If the queue is full and therefore cannot accept more messages.

Returned Value

None

Required Configuration

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

Callers

Application and ISRs.

Notes/Warnings

1. Queues must be created before they are used.
2. Possible combinations of options are: 
   OS_OPT_POST_FIFO
OS_OPT_POST_LIFO
OS_OPT_POST_FIFO + OS_OPT_POST_ALL
OS_OPT_POST_LIFO + OS_OPT_POST_ALL
OS_OPT_POST_FIFO + OS_OPT_POST_NO_SCHED
OS_OPT_POST_LIFO + OS_OPT_POST_NO_SCHED
OS_OPT_POST_FIFO + OS_OPT_POST_ALL + OS_OPT_POST_NO_SCHED
OS_OPT_POST_LIFO + OS_OPT_POST_ALL + OS_OPT_POST_NO_SCHED
3. Although the example below shows calling OSQPost() from a task, it can also be called from an ISR.

Example Usage

          OS_Q         CommQ;
          CPU_INT08U   CommRxBuf[100];
           
           
          void CommTaskRx (void *p_arg)
          {
              OS_ERR  err;
           
           
              (void)&p_arg;
              while (DEF_ON) {
                  :
                  :
                  OSQPost(&CommQ,
                          &CommRxBuf[0],
                           sizeof(CommRxBuf),
                           OS_OPT_POST_FIFO + OS_OPT_POST_ALL + OS_OPT_POST_NO_SCHED,
                          &err);
                  /* Check "err" */
                  :
                  :
              }
          }