OSFlagPendAbort

Description

Aborts and readies any tasks currently waiting on an event flag group. This function would be used by another task to fault abort the wait on the event flag group, rather than to normally signal the event flag group via OSFlagPost().

Files

os.h/os_flag.c

Prototype

OS_OBJ_QTY  OSFlagPendAbort (OS_FLAG_GRP  *p_grp,
                             OS_OPT        opt,
                             OS_ERR       *p_err)

Arguments

p_grp

is a pointer to the event flag group for which pend(s) must be aborted.

opt

determines the type of abort performed.

OS_OPT_PEND_ABORT_1

Aborts the pend of only the highest priority task waiting on the event flag group.

OS_OPT_PEND_ABORT_ALL

Aborts the pend of all the tasks waiting on the event flag group.

OS_OPT_POST_NO_SCHED

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

You would use this option if the task calling OSFlagPendAbort() will perform additional pend aborts, rescheduling will take place at completion, and when multiple pend aborts are to take effect simultaneously.

p_err

is a pointer to a variable that holds an error code. OSFlagPendAbort() sets *p_err to one of the following:

OS_ERR_NONE

at least one task waiting on the event flag group was readied and informed of the aborted wait. The return value indicates the number of tasks where a wait on the event flag group was aborted.

OS_ERR_OBJ_PTR_NULL

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if p_grp 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_grp is not pointing to an event flag group.

OS_ERR_OPT_INVALID

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if specifying an invalid option.

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: This function cannot be called from an ISR.

OS_ERR_PEND_ABORT_NONE

No task was aborted since no task was waiting.

Returned Value

OSFlagPendAbort() returns the number of tasks made ready-to-run by this function. Zero indicates that no tasks were pending on the event flag group and thus this function had no effect.

Required Configuration

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

Callers

Application.

Notes/Warnings

1. Event flag groups must be created before they are used.

Example Usage

          OS_FLAG_GRP  EngineStatus;
           
           
          void Task (void *p_arg)
          {
              OS_ERR      err;
              OS_OBJ_QTY  nbr_tasks;
           
           
              (void)&p_arg;
              while (DEF_ON) {
                  :
                  :
                  nbr_tasks = OSFlagPendAbort(&EngineStatus,
                                              OS_OPT_PEND_ABORT_ALL,
                                              &err);
                  /* Check "err" */
                  :
                  :
              }
          }