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 will be returned to its original priority 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 equivalent number of times to release the mutex.
Files
os.h/os_mutex.c
Prototype
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_NESTING
If the calling task already owns the mutex and it has not posted all nested values.
OS_ERR_MUTEX_OWNER
If the calling task already owns the mutex.
OS_ERR_OBJ_PTR_NULL
If OS_CFG_ARG_CHK_EN is set to 1 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 1 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 1 in os_cfg.h: if a valid option is not specified.
OS_ERR_PEND_ISR
If OS_CFG_CALLED_FROM_ISR_CHK_EN set to 1 in os_cfg.h: if attempting to acquire the mutex from an ISR.
OS_ERR_SCHED_LOCKED
If calling this function when the scheduler is locked
OS_ERR_TIMEOUT
If the mutex is 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-OS-III Configuration Manual
Callers
Application.
Notes/Warnings
Mutexes must be created before they are used.