OSMutexPendAbort

Description

Aborts and readies all the tasks currently pending on a mutex. This function should be used to fault-abort the wait on the mutex rather than to normally signal the mutex via OSMutexPost().

Files

os.h/os_mutex.c

Prototype

OS_OBJ_QTY  OSMutexPendAbort (OS_MUTEX  *p_mutex,
                              OS_OPT     opt,
                              OS_ERR    *p_err)

Arguments

p_mutex

is a pointer to the mutex.

opt

specifies whether to abort only the highest-priority task waiting on the mutex or all tasks waiting on the mutex:

OS_OPT_PEND_ABORT_1

to abort only the highest-priority task waiting on the mutex.

OS_OPT_PEND_ABORT_ALL

to abort all tasks waiting on the mutex.

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.

The user would select this option if the task calling OSMutexPendAbort() will be doing additional pend aborts, rescheduling should not take place until all tasks are completed, and multiple pend aborts should take place simultaneously.

p_err

is a pointer to a variable that is used to hold an error code:

OS_ERR_NONE

If at least one task was aborted. Check the return value for the number of tasks aborted.

OS_ERR_OBJ_PTR_NULL

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if p_mutex 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 the caller does not pass a pointer to a mutex.

OS_ERR_OPT_INVALID

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if the caller specified 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: if attempting to call this function from an ISR

OS_ERR_PEND_ABORT_NONE

If no tasks were aborted.

Returned Value

OSMutexPendAbort() returns the number of tasks made ready-to-run by this function. Zero either indicates an error or that no tasks were pending on the mutex.

Required Configuration

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

Callers

Application.

Notes/Warnings

1. Mutexes must be created before they are used.

Example Usage

          OS_MUTEX  DispMutex;
           
           
          void  DispTask (void *p_arg)
          {
              OS_ERR      err;
              OS_OBJ_QTY  qty;
           
           
              (void)&p_arg;
              while (DEF_ON) {
                  :
                  :
                  qty = OSMutexPendAbort(&DispMutex,
                                          OS_OPT_PEND_ABORT_ALL,
                                         &err);
                  /* Check "err" */
                  :
                  :
              }
          }