OSMutexPost

Description

A mutex is signaled (i.e., released) by calling OSMutexPost(). You should call this function only if you acquired the mutex by first calling OSMutexPend(). If the priority of the task that owns the mutex has been raised when a higher priority task attempted to acquire the mutex, the priority of the owning task will be set to the highest priority in the owning task's mutex group or its base priority, whichever is higher. If one or more tasks are waiting for the mutex, the mutex is given to the highest-priority task waiting on the mutex. The scheduler is then called to determine if the awakened task is now the highest-priority task ready-to-run, and if so, a context switch is performed to run the readied task. If no task is waiting for the mutex, the mutex value is simply set to available.

Prototype

void  OSMutexPost (OS_MUTEX  *p_mutex,
                   OS_OPT     opt,
                   OS_ERR    *p_err);

Arguments

p_mutex

is a pointer to the mutex.

opt

determines the type of POST performed.

OS_OPT_POST_NONE

No special option selected.

OS_OPT_POST_NO_SCHED

Do not call the scheduler after the post, therefore the caller is resumed even if the mutex was posted and tasks of higher priority are waiting for the mutex.

Use this option if the task calling OSMutexPost() will be doing additional posts, if the user does not want to reschedule until all is complete, and multiple posts should take effect simultaneously.

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 is available.

OS_ERR_MUTEX_NESTING

If the owner of the mutex has the mutex nested and it has not fully un-nested.

OS_ERR_MUTEX_NOT_OWNER

If the caller is not the owner of the mutex and therefore is not allowed to release it.

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 not passing 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 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_POST_ISR

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

Returned Value

None

Required Configuration

OS_CFG_MUTEX_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  TaskX (void *p_arg)
          {
              OS_ERR  err;
           
           
              (void)&p_arg;
              while (DEF_ON) {
                  :
                  OSMutexPost(&DispMutex,
                               OS_OPT_POST_NONE,
                              &err);
                  /* Check "err" */
                  :
                  :
              }
          }