Xenomai  3.0.8
Mutex services

POSIXish mutual exclusion servicesl. More...

Collaboration diagram for Mutex services:

Data Structures

struct  RT_MUTEX_INFO
 Mutex status descriptor. More...
 

Functions

int rt_mutex_create (RT_MUTEX *mutex, const char *name)
 Create a mutex. More...
 
int rt_mutex_delete (RT_MUTEX *mutex)
 Delete a mutex. More...
 
int rt_mutex_acquire_timed (RT_MUTEX *mutex, const struct timespec *abs_timeout)
 Acquire/lock a mutex (with absolute timeout date). More...
 
static int rt_mutex_acquire_until (RT_MUTEX *mutex, RTIME timeout)
 Acquire/lock a mutex (with absolute scalar timeout). More...
 
static int rt_mutex_acquire (RT_MUTEX *mutex, RTIME timeout)
 Acquire/lock a mutex (with relative scalar timeout). More...
 
int rt_mutex_release (RT_MUTEX *mutex)
 Release/unlock a mutex. More...
 
int rt_mutex_inquire (RT_MUTEX *mutex, RT_MUTEX_INFO *info)
 Query mutex status. More...
 
int rt_mutex_bind (RT_MUTEX *mutex, const char *name, RTIME timeout)
 Bind to a mutex. More...
 
int rt_mutex_unbind (RT_MUTEX *mutex)
 Unbind from a mutex. More...
 

Detailed Description

POSIXish mutual exclusion servicesl.

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.

Function Documentation

◆ rt_mutex_acquire()

int rt_mutex_acquire ( RT_MUTEX *  mutex,
RTIME  timeout 
)
inlinestatic

Acquire/lock a mutex (with relative scalar timeout).

This routine is a variant of rt_mutex_acquire_timed() accepting a relative timeout specification expressed as a scalar value.

Parameters
mutexThe mutex descriptor.
timeoutA delay expressed in clock ticks. Passing TM_INFINITE the caller to block indefinitely. Passing TM_NONBLOCK causes the service to return immediately without blocking in case mutex is already locked by another task.
Tags api-tags "xthread-only, switch-primary"

◆ rt_mutex_acquire_timed()

int rt_mutex_acquire_timed ( RT_MUTEX *  mutex,
const struct timespec *  abs_timeout 
)

Acquire/lock a mutex (with absolute timeout date).

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. Xenomai mutexes are implicitely recursive and implement the priority inheritance protocol.

Parameters
mutexThe mutex descriptor.
abs_timeoutAn absolute date expressed in clock ticks, specifying a time limit to wait for the mutex to be available (see note). Passing NULL the caller to block indefinitely. Passing { .tv_sec = 0, .tv_nsec = 0 } causes the service to return immediately without blocking in case mutex is already locked by another task.
Returns
Zero is returned upon success. Otherwise:
  • -ETIMEDOUT is returned if abs_timeout is reached before the mutex is available.
  • -EWOULDBLOCK is returned if timeout is { .tv_sec = 0, .tv_nsec = 0 } and the mutex is not immediately available.
  • -EINTR is returned if rt_task_unblock() was called for the current task.
  • -EINVAL is returned if mutex is not a valid mutex descriptor.
  • -EIDRM is returned if mutex is deleted while the caller was waiting on it. In such event, mutex is no more valid upon return of this service.
  • -EPERM is returned if this service should block, but was not called from a Xenomai thread.
Tags api-tags "xthread-only, switch-primary"
Side effects
Over the Cobalt core, an Alchemy task with priority zero keeps running in primary mode until it releases the mutex, at which point it is switched back to secondary mode automatically.
Note
abs_timeout is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

◆ rt_mutex_acquire_until()

int rt_mutex_acquire_until ( RT_MUTEX *  mutex,
RTIME  abs_timeout 
)
inlinestatic

Acquire/lock a mutex (with absolute scalar timeout).

This routine is a variant of rt_mutex_acquire_timed() accepting an absolute timeout specification expressed as a scalar value.

Parameters
mutexThe mutex descriptor.
abs_timeoutAn absolute date expressed in clock ticks. Passing TM_INFINITE the caller to block indefinitely. Passing TM_NONBLOCK causes the service to return immediately without blocking in case mutex is already locked by another task.
Tags api-tags "xthread-only, switch-primary"

◆ rt_mutex_bind()

int rt_mutex_bind ( RT_MUTEX *  mutex,
const char *  name,
RTIME  timeout 
)

Bind to a mutex.

This routine creates a new descriptor to refer to an existing mutex identified by its symbolic name. If the object not exist on entry, the caller may block until a mutex of the given name is created.

Parameters
mutexThe address of a mutex descriptor filled in by the operation. Contents of this memory is undefined upon failure.
nameA valid NULL-terminated name which identifies the mutex to bind to. This string should match the object name argument passed to rt_mutex_create().
timeoutThe 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.
Returns
Zero is returned upon success. Otherwise:
  • -EINTR is returned if rt_task_unblock() was called for the current task before the retrieval has completed.
  • -EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and the searched object is not registered on entry.
  • -ETIMEDOUT is returned if the object cannot be retrieved within the specified amount of time.
  • -EPERM is returned if this service should block, but was not called from a Xenomai thread.
Tags api-tags "xthread-nowait, switch-primary"
Note
The timeout value is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

◆ rt_mutex_create()

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.

Parameters
mutexThe address of a mutex descriptor which can be later used to identify uniquely the created object, upon success of this call.
nameAn ASCII string standing for the symbolic name of the mutex. When non-NULL and non-empty, a copy of this string is used for indexing the created mutex into the object registry.
Returns
Zero is returned upon success. Otherwise:
  • -ENOMEM is returned if the system fails to get memory from the main heap in order to create the mutex.
  • -EEXIST is returned if the name is conflicting with an already registered mutex.
  • -EPERM is returned if this service was called from an invalid context, e.g. interrupt or non-Xenomai thread.
Tags api-tags "xthread-only, mode-unrestricted, switch-secondary"
Note
Mutexes can be shared by multiple processes which belong to the same Xenomai session.

◆ rt_mutex_delete()

int rt_mutex_delete ( RT_MUTEX *  mutex)

Delete a mutex.

This routine deletes a mutex object previously created by a call to rt_mutex_create().

Parameters
mutexThe mutex descriptor.
Returns
Zero is returned upon success. Otherwise:
  • -EINVAL is returned if alarm is not a valid mutex descriptor.
  • -EPERM is returned if this service was called from an asynchronous context.
  • -EBUSY is returned upon an attempt to destroy the object referenced by mutex while it is referenced (for example, while being used in a rt_mutex_acquite(), rt_mutex_acquire_timed() or rt_mutex_acquire_until() by another task).
Tags api-tags "mode-unrestricted, switch-secondary"

◆ rt_mutex_inquire()

int rt_mutex_inquire ( RT_MUTEX *  mutex,
RT_MUTEX_INFO info 
)

Query mutex status.

This routine returns the status information about the specified mutex.

Parameters
mutexThe mutex descriptor.
infoA pointer to the returnbuffer" to copy the information to.
Returns
Zero is returned and status information is written to the structure pointed at by info upon success. Otherwise:
  • -EINVAL is returned if mutex is not a valid mutex descriptor.
  • -EPERM is returned if this service is called from an interrupt context.
Tags api-tags "xthread-only, switch-primary"

◆ rt_mutex_release()

int rt_mutex_release ( RT_MUTEX *  mutex)

Release/unlock a mutex.

This routine releases a mutex object previously locked by a call to rt_mutex_acquire() or rt_mutex_acquire_until(). 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.

Parameters
mutexThe mutex descriptor.
Returns
Zero is returned upon success. Otherwise:
  • -EINVAL is returned if alarm is not a valid mutex descriptor.
  • -EPERM is returned if mutex is not owned by the current task, or more generally if this service was called from a context which cannot own any mutex (e.g. interrupt context).
Tags api-tags "xthread-only, switch-primary"

◆ rt_mutex_unbind()

int rt_mutex_unbind ( RT_MUTEX *  mutex)

Unbind from a mutex.

Parameters
mutexThe mutex descriptor.

This routine releases a previous binding to a mutex. After this call has returned, the descriptor is no more valid for referencing this object.