OSMutexPend

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 owning task will be 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 nesting. The same task can call OSMutexPend() multiple times. However, the same task must then call OSMutexPost() an 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.

timeout

specifies a timeout value (in clock ticks) and is used to allow the task to resume execution if the mutex is not signaled (i.e., posted to) within the specified timeout. A timeout value of 0 indicates that the task wants to wait forever for the mutex. The timeout value is not synchronized with the clock tick. The timeout count is decremented on the next clock tick, which could potentially occur immediately.

opt

determines whether the user wants to block if the mutex is not available or not. This argument must be set to either:

OS_OPT_PEND_BLOCKING, or 
OS_OPT_PEND_NON_BLOCKING

Note that the timeout argument should be set to 0 when specifying OS_OPT_PEND_NON_BLOCKING since the timeout value is irrelevant using this option.

p_ts

is a pointer to a timestamp indicating when the mutex was posted, the pend was aborted, or the mutex was deleted. If passing a NULL pointer (i.e., (CPU_TS *)0), the caller will not receive the timestamp. In other words, passing a NULL pointer is valid and indicates that the timestamp is not required.

A timestamp is useful when it is important for a task to know when the mutex was posted, or how long it took for the task to resume after the mutex was posted. In the latter case, the user must call OS_TS_GET() and compute the difference between the current value of the timestamp and *p_ts. In other words:

delta = OS_TS_GET() - *p_ts;

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_OWNER

If the calling task already owns the mutex.

OS_ERR_MUTEX_OVF

The mutex nesting counter overflowed.

OS_ERR_OBJ_DEL

If the mutex was deleted.

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 user did 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 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 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 the scheduler is locked.

OS_ERR_STATUS_INVALID

If the pend status has an invalid value.

OS_ERR_TIMEOUT

If the mutex 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 µ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" */
                  :
                  :
              }
          }