Page Comparison

Description

Acquire a mutual exclusion semaphore. If a task calls OSMutexPend() and the mutex is available, OSMutexPend() gives the mutex to the caller and returns to its caller. Note that nothing is actually given to the caller except that if p_err is set to OS_ERR_NONE, the caller can assume that it owns the mutex. However, if the mutex is already owned by another task, OSMutexPend() places the calling task in the wait list for the mutex. The task waits until the task that owns the mutex releases the mutex and therefore the resource, or until the specified timeout expires. If the mutex is signaled before the timeout expires, µC/OS-III resumes the highest-priority task that is waiting for the mutex. Note that if the mutex is owned by a lower-priority task, OSMutexPend() raises the priority of the task that owns the mutex to the same priority as the task requesting the mutex. The priority of the owner owning task will be returned to its original priority when set to the highest priority in the owning task's mutex group or its base priority, whichever is higher, when the owner releases the mutex (see OSMutexPost()). OSMutexPend() allows  allows nesting. The same task can call OSMutexPend() multiple times. However, the same task must then call OSMutexPost() an equivalent equal number of times to release the mutex.

Files

os.h/os_mutex.c

Prototype

void  OSMutexPend (OS_MUTEX  *p_mutex,
                   OS_TICK    timeout,
                   OS_OPT     opt,
                   CPU_TS    *p_ts,
                   OS_ERR    *p_err)

Arguments

p_mutex

is a pointer to the mutex.

...

If the call is successful and the mutex is available.

OS_ERR_MUTEX_NESTINGOWNER

If the calling task already owns the mutex and it has not posted all nested values.

OS_ERR_MUTEX_OWNER_OVF

The mutex nesting counter overflowed.

OS_ERR_OBJ_DEL

If the calling task already owns the mutex was deleted.

OS_ERR_OBJ_PTR_NULL

If OS_CFG_ARG_CHK_EN is set to 1 in DEF_ENABLED in os_cfg.h: if p_mutex is a NULL pointer.

...

If OS_CFG_OBJ_TYPE_CHK_EN is set to 1 in DEF_ENABLED in os_cfg.h: if the user did not pass a pointer to a mutex.

...

If OS_CFG_ARG_CHK_EN is set to 1 in 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

If OS_CFG_MUTEX_PEND_ABORT_EN is set to DEF_ENABLED in os_cfg.h: the pend was aborted by another task.

OS_ERR_PEND_ISR

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

OS_ERR_PEND_WOULD_BLOCK

If the mutex was not available and OS_OPT_PEND_NON_BLOCKING is specified.

OS_ERR_SCHED_LOCKED

If calling this function when the scheduler is locked.

OS_ERR_STATUS_INVALID

If the pend status has an invalid value.

OS_ERR_TIMEOUT

If the mutex is was not available within the specified timeout.

Returned Value

None

Required Configuration

OS_CFG_MUTEX_EN must be enabled in os_cfg.h. Refer to uCµ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;
              CPU_TS  ts;
           
           
              (void)&p_arg;
              while (DEF_ON) {
                  :
                  OSMutexPend(&DispMutex,
                               0,
                               OS_OPT_PEND_BLOCKING,
                              &ts,
                              &err);
                  /* Check "err" */
                  :
                  :
              }
          }