OSTaskSemPendAbort

Description

OSTaskSemPendAbort() aborts and readies a task currently waiting on its built-in semaphore. This function should be used to fault-abort the wait on the task’s semaphore, rather than to normally signal the task via OSTaskSemPost().

Files

os.h/os_task.c

Prototype

CPU_BOOLEAN  OSTaskSemPendAbort (OS_TCB  *p_tcb,
                                 OS_OPT   opt,
                                 OS_ERR  *p_err)

Arguments

p_tcb

is a pointer to the task for which the pend must be aborted. Note that it does not make sense to pass a NULL pointer or the address of the calling task’s TCB since, by definition, the calling task cannot be pending.

opt

provides options for this function.

OS_OPT_POST_NONE

no option specified, call the scheduler by default.

OS_OPT_POST_NO_SCHED

specifies that the scheduler should not be called even if the pend of a higher-priority task has been aborted. Scheduling will need to occur from another function.

Use this option if the task calling OSTaskSemPendAbort() will be doing additional pend aborts, rescheduling will not take place until finished, and multiple pend aborts are to take effect simultaneously.

p_err

is a pointer to a variable that holds an error code:

OS_ERR_NONE

the pend was aborted for the specified task.

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_ISR

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

OS_ERR_PEND_ABORT_NONE

If the task was not waiting for a signal.

OS_ERR_PEND_ABORT_SELF

If p_tcb is a NULL pointer or the TCB of the calling task is specified. The user is attempting to pend abort the calling task, which makes no sense since, by definition, the calling task is not pending.

Returned Value

OSTaskSemPendAbort() returns DEF_TRUE if the task was made ready-to-run by this function. DEF_FALSE indicates that the task was not pending, or an error occurred.

Required Configuration

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

Callers

Application.

Notes/Warnings

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

Example Usage

          OS_TCB  CommRxTaskTCB;
           
           
          void CommTask (void *p_arg)
          {
              OS_ERR      err;
              CPU_BOOLEAN  aborted;
           
           
              (void)&p_arg;
              while (DEF_ON) {
                  :
                  :
                  aborted = OSTaskSemPendAbort(&CommRxTaskTCB,
                                                OS_OPT_POST_NONE,
                                               &err);
                  /* Check "err" */
                  :
                  :
              }
          }