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

mutex	The mutex descriptor.
timeout	A 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

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

mutex	The mutex descriptor.
abs_timeout	An 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

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

mutex	The mutex descriptor.
abs_timeout	An 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

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

mutex	The address of a mutex descriptor filled in by the operation. Contents of this memory is undefined upon failure.
name	A valid NULL-terminated name which identifies the mutex to bind to. This string should match the object name argument passed to rt_mutex_create().
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.

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

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

mutex	The address of a mutex descriptor which can be later used to identify uniquely the created object, upon success of this call.
name	An 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

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

mutex

The 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_acquire(), rt_mutex_acquire_timed() or rt_mutex_acquire_until() by another task).

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

mutex	The mutex descriptor.
info	A pointer to the return buffer" 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

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

mutex

The 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

xthread-only, switch-primary

rt_mutex_unbind()

int rt_mutex_unbind

(

RT_MUTEX *

mutex

)

Unbind from a mutex.

Parameters

mutex

The 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.