OSTaskSemPend

Description

OSTaskSemPend() allows a task to wait for a signal to be sent by another task or ISR without going through an intermediate object such as a semaphore. If the task was previously signaled when OSTaskSemPend() is called then, the caller resumes.

If no signal was received by the task and OS_OPT_PEND_BLOCKING is specified for the opt argument, OSTaskSemPend() suspends the current task until either a signal is received, or a user-specified timeout expires. A pended task suspended with OSTaskSuspend() can receive signals. However, the task remains suspended until it is resumed by calling OSTaskResume().

If no signals were sent to the task and OS_OPT_PEND_NON_BLOCKING was specified for the opt argument, OSTaskSemPend() returns to the caller with an appropriate error code and returns a signal count of 0.

Files

os.h/os_task.c

Prototype

OS_SEM_CTR  OSTaskSemPend (OS_TICK   timeout,
                           OS_OPT    opt,
                           CPU_TS   *p_ts,
                           OS_ERR   *p_err)

Arguments

timeout

allows the task to resume execution if a signal 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 signal. 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 the user wants to block or not, if a signal was not sent to the task. Set this argument 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_ts

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

A timestamp is useful when the task is to know when the semaphore was posted, or how long it took for the task to resume after the semaphore 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 signal is received.

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_PEND_ABORT

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

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 signal was received.

OS_ERR_SCHED_LOCKED

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

OS_ERR_STATUS_INVALID

If the pend status has an invalid value.

OS_ERR_TIMEOUT

If a signal is not received within the specified timeout.

Returned Value

The current value of the signal counter after it has been decremented. In other words, the number of signals still remaining in the signal counter.

Required Configuration

Always enabled.

Callers

Application.

Notes/Warnings

1. Do not call OSTaskSemPend() from an ISR.

Example Usage

          void CommTask(void *p_arg)
          {
              OS_ERR      err;
              OS_SEM_CTR  ctr;
              CPU_TS      ts;
           
           
              (void)&p_arg;
              while (DEF_ON) {
                  :
                  ctr = OSTaskSemPend(100,
                                      OS_OPT_PEND_BLOCKING,
                                      &ts,
                                      &err);
                  /* Check "err" */
                  :
                  :
              }
          }