OSMutexDel

Description

Deletes a mutex. This function makes all pending tasks ready to run and clears the mutex data. It also sets the owning task's priority to the highest priority in the owner's task mutex group or its base priority, whichever is higher. Generally speaking, before deleting a mutex, first delete all the tasks that access the mutex. However, as a guideline, do not delete kernel objects at run-time.

Files

os.h/os_mutex.c

Prototype

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

Arguments

p_mutex

is a pointer to the mutex to delete.

opt

specifies whether to delete the mutex only if there are no pending tasks (OS_OPT_DEL_NO_PEND), or whether to always delete the mutex regardless of whether tasks are pending or not (OS_OPT_DEL_ALWAYS). In this case, all pending tasks are readied.

p_err

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

OS_ERR_NONE

If the call is successful and the mutex has been deleted.

OS_ERR_DEL_ISR

If OS_CFG_CALLED_FROM_ISR_CHK_EN set to DEF_ENABLED in os_cfg.h: if attempting to delete a mutex from an ISR.

OS_ERR_ILLEGAL_DEL_RUN_TIME

If OS_SAFETY_CRITICAL_IEC61508 is defined: you are trying to delete the mutex after you called OSStart().

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 p_mutex is not pointing to a mutex.

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_TASK_WAITING

If one or more task are waiting on the mutex and OS_OPT_DEL_NO_PEND is specified.

Returned Value

The number of tasks that were waiting for the mutex. Zero either indicates an error or that no tasks were pending on the mutex.

Required Configuration

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

Callers

Application.

Notes/Warnings

1. Use this call with care as other tasks may expect the presence of the mutex.

Example Usage

          OS_MUTEX  DispMutex;
           
           
          void Task (void *p_arg)
          {
              OS_ERR      err;
              OS_OBJ_QTY  qty;
           
           
              (void)&p_arg;
              while (DEF_ON) {
                  :
                  :
                  qty = OSMutexDel(&DispMutex,
                                    OS_OPT_DEL_ALWAYS,
                                   &err);
                  /* Check "err" */
                  :
                  :
              }
          }