NAME | SYNOPSIS | FEATURES | DESCRIPTION | RESTRICTIONS | RETURN VALUE | ERRORS | ATTRIBUTES | SEE ALSO
#include <sync/chMutex.h>int mutexInit(KnMutex * mutex);
MUTEX
Mutexes are binary semaphores used to protect shared data from concurrent access: a mutex is a two state-variable - free or locked.
Mutexes are KnMutex structures allocated in the user memory.
mutexInit initializes the mutex the address of which is mutex. The mutex is initialized as free.
Statically allocated mutexes can be initialized using the K_KNMUTEX_INITIALIZER macro, which initializes the mutex as free. This macro is used as follows:
KnMutex myMutex = K_KNMUTEX_INITIALIZER ;
mutexGet is used to acquire a mutex. If the mutex is free, it becomes locked and the caller continues its execution normally. If the mutex is locked, the caller is blocked until the mutex is released.
mutexRel is used to release a mutex. If threads are blocked behind the mutex, one of them is awakened.
mutexTry is only an attempt to acquire the mutex: it has the same effect as mutexGet, except that if the mutex is locked, the thread is not blocked (a return code is provided).
Semaphores initialized with a count value of 1 (see semInit (2K) ) are functionally equivalent to mutexes. However, there are implementation differences between mutexes and semaphores which make them behave differently. First, mutex operations are implemented so that optimal performance is obtained when no thread state change is needed (i.e. when a thread acquires a free mutex, or when a mutex is released and no thread is waiting for it). A consequence of this optimization is that mutexes do not guarantee fairness.
A blocking mutexGet is NONABORTABLE (see threadAbort (2K)).
A user application and a supervisor application may not share a mutex.
On the contrary, two user applications may share a mutex by mapping it in both user address spaces. Such shared mutexes must be dynamically allocated mutexes.
mutexTry returns 0 if the mutex was already locked, 1 if it was free. Upon successful completion of mutexInit, mutexGet and mutexRel, 0 is returned. Otherwise, a negative error code is returned.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | FEATURES | DESCRIPTION | RESTRICTIONS | RETURN VALUE | ERRORS | ATTRIBUTES | SEE ALSO