OSTaskQPendAbort

Description

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

Files

os.h/os_task.c

Prototype

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

Arguments

p_tcb

is a pointer to the task for which the pend needs to be aborted. Note that it doesn’t 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.

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 OSTaskQPendAbort() will do additional pend aborts, rescheduling will take place when completed, and multiple pend aborts should take effect simultaneously.

p_err

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

OS_ERR_NONE

the task was readied by another task and it was informed of the aborted wait.

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 pending on the task’s message queue.

OS_ERR_PEND_ABORT_SELF

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if p_tcb is a NULL pointer. The user is attempting to pend abort the calling task which makes no sense as the caller, by definition, is not pending.

Returned Value

OSTaskQPendAbort() 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_Q_EN and OS_CFG_TASK_Q_PEND_ABORT_EN must be enabled in os_cfg.h. Refer to µC-OS-III Configuration Manual.

Callers

Application.

Notes/Warnings

None

Example Usage

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