|
|
|
A mutex is a MUTual EXclusion object, and is useful for protecting shared data structures from concurrent modifications, and implementing critical sections and monitors.
A mutex has two possible states: unlocked (not owned by any task), and locked (owned by one task). A mutex can never be owned by two different tasks simultaneously. A task attempting to lock a mutex that is already locked by another task is blocked until the latter unlocks the mutex first.
Xenomai mutex services enforce a priority inheritance protocol in order to solve priority inversions.
Files | |
| file | mutex.c |
| This file is part of the Xenomai project. | |
Functions | |
| int | rt_mutex_create (RT_MUTEX *mutex, const char *name) |
| int | rt_mutex_delete (RT_MUTEX *mutex) |
| int | rt_mutex_acquire (RT_MUTEX *mutex, RTIME timeout) |
| int | rt_mutex_release (RT_MUTEX *mutex) |
| int | rt_mutex_inquire (RT_MUTEX *mutex, RT_MUTEX_INFO *info) |
| int | rt_mutex_bind (RT_MUTEX *mutex, const char *name, RTIME timeout) |
| static int | rt_mutex_unbind (RT_MUTEX *mutex) |
| int rt_mutex_acquire | ( | RT_MUTEX * | mutex, | |
| RTIME | timeout | |||
| ) |
Acquire a mutex.
Attempt to lock a mutex. The calling task is blocked until the mutex is available, in which case it is locked again before this service returns. Mutexes have an ownership property, which means that their current owner is tracked. Xenomai mutexes are implicitely recursive and implement the priority inheritance protocol.
Since a nested locking count is maintained for the current owner, rt_mutex_acquire() and rt_mutex_release() must be used in pairs.
Tasks pend on mutexes by priority order.
| mutex | The descriptor address of the mutex to acquire. | |
| timeout | The number of clock ticks to wait for the mutex to be available to the calling task (see note). Passing TM_INFINITE causes the caller to block indefinitely until the mutex is available. Passing TM_NONBLOCK causes the service to return immediately without waiting if the mutex is still locked by another task. |
Environments:
This service can be called from:
Rescheduling: always unless the request is immediately satisfied or timeout specifies a non-blocking operation. If the caller is blocked, the current owner's priority might be temporarily raised as a consequence of the priority inheritance protocol.
| int rt_mutex_bind | ( | RT_MUTEX * | mutex, | |
| const char * | name, | |||
| RTIME | timeout | |||
| ) |
Bind to a mutex.
This user-space only service retrieves the uniform descriptor of a given Xenomai mutex identified by its symbolic name. If the mutex does not exist on entry, this service blocks the caller until a mutex of the given name is created.
| name | A valid NULL-terminated name which identifies the mutex to bind to. | |
| mutex | The address of a mutex descriptor retrieved by the operation. Contents of this memory is undefined upon failure. | |
| timeout | The number of clock ticks to wait for the registration to occur (see note). Passing TM_INFINITE causes the caller to block indefinitely until the object is registered. Passing TM_NONBLOCK causes the service to return immediately without waiting if the object is not registered on entry. |
Environments:
This service can be called from:
Rescheduling: always unless the request is immediately satisfied or timeout specifies a non-blocking operation.
| int rt_mutex_create | ( | RT_MUTEX * | mutex, | |
| const char * | name | |||
| ) |
Create a mutex.
Create a mutual exclusion object that allows multiple tasks to synchronize access to a shared resource. A mutex is left in an unlocked state after creation.
| mutex | The address of a mutex descriptor Xenomai will use to store the mutex-related data. This descriptor must always be valid while the mutex is active therefore it must be allocated in permanent memory. | |
| name | An ASCII string standing for the symbolic name of the mutex. When non-NULL and non-empty, this string is copied to a safe place into the descriptor, and passed to the registry package if enabled for indexing the created mutex. |
Environments:
This service can be called from:
Rescheduling: possible.
| int rt_mutex_delete | ( | RT_MUTEX * | mutex | ) |
Delete a mutex.
Destroy a mutex and release all the tasks currently pending on it. A mutex exists in the system since rt_mutex_create() has been called to create it, so this service must be called in order to destroy it afterwards.
| mutex | The descriptor address of the affected mutex. |
Environments:
This service can be called from:
Rescheduling: possible.
| int rt_mutex_inquire | ( | RT_MUTEX * | mutex, | |
| RT_MUTEX_INFO * | info | |||
| ) |
Inquire about a mutex.
Return various information about the status of a given mutex.
| mutex | The descriptor address of the inquired mutex. | |
| info | The address of a structure the mutex information will be written to. |
Environments:
This service can be called from:
Rescheduling: never.
| int rt_mutex_release | ( | RT_MUTEX * | mutex | ) |
Unlock mutex.
Release a mutex. If the mutex is pended, the first waiting task (by priority order) is immediately unblocked and transfered the ownership of the mutex; otherwise, the mutex is left in an unlocked state.
| mutex | The descriptor address of the released mutex. |
Environments:
This service can be called from:
Rescheduling: possible.
| int rt_mutex_unbind | ( | RT_MUTEX * | mutex | ) | [inline, static] |
Unbind from a mutex.
This user-space only service unbinds the calling task from the mutex object previously retrieved by a call to rt_mutex_bind().
| mutex | The address of a mutex descriptor to unbind from. |
Rescheduling: never.
1.5.3