Mutex services.
[POSIX skin.]

Collaboration diagram for Mutex services.:

---

Detailed Description

Mutex services.

A mutex is a MUTual EXclusion device, 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 thread), and locked (owned by one thread). A mutex can never be owned by two different threads simultaneously. A thread attempting to lock a mutex that is already locked by another thread is suspended until the owning thread unlocks the mutex first.

Before it can be used, a mutex has to be initialized with pthread_mutex_init(). An attribute object, which reference may be passed to this service, allows to select the features of the created mutex, namely its type (see pthread_mutexattr_settype()), the priority protocol it uses (see pthread_mutexattr_setprotocol()) and whether it may be shared between several processes (see pthread_mutexattr_setpshared()).

By default, Xenomai POSIX skin mutexes are of the normal type, use no priority protocol and may not be shared between several processes.

Note that only pthread_mutex_init() may be used to initialize a mutex, using the static initializer PTHREAD_MUTEX_INITIALIZER is not supported.

Functions
int	pthread_mutex_init (pthread_mutex_t *mx, const pthread_mutexattr_t *attr)
	Initialize a mutex.
int	pthread_mutex_destroy (pthread_mutex_t *mx)
	Destroy a mutex.
int	pthread_mutex_trylock (pthread_mutex_t *mx)
	Attempt to lock a mutex.
int	pthread_mutex_lock (pthread_mutex_t *mx)
	Lock a mutex.
int	pthread_mutex_timedlock (pthread_mutex_t *mx, const struct timespec *to)
	Attempt, during a bounded time, to lock a mutex.
int	pthread_mutex_unlock (pthread_mutex_t *mx)
	Unlock a mutex.
int	pthread_mutexattr_init (pthread_mutexattr_t *attr)
	Initialize a mutex attributes object.
int	pthread_mutexattr_destroy (pthread_mutexattr_t *attr)
	Destroy a mutex attributes object.
int	pthread_mutexattr_gettype (const pthread_mutexattr_t *attr, int *type)
	Get the mutex type attribute from a mutex attributes object.
int	pthread_mutexattr_settype (pthread_mutexattr_t *attr, int type)
	Set the mutex type attribute of a mutex attributes object.
int	pthread_mutexattr_getprotocol (const pthread_mutexattr_t *attr, int *proto)
	Get the protocol attribute from a mutex attributes object.
int	pthread_mutexattr_setprotocol (pthread_mutexattr_t *attr, int proto)
	Set the protocol attribute of a mutex attributes object.
int	pthread_mutexattr_getpshared (const pthread_mutexattr_t *attr, int *pshared)
	Get the process-shared attribute of a mutex attributes object.
int	pthread_mutexattr_setpshared (pthread_mutexattr_t *attr, int pshared)
	Set the process-shared attribute of a mutex attributes object.

---

Function Documentation

int pthread_mutex_destroy

(

pthread_mutex_t *

mx

)

Destroy a mutex.

This service destroys the mutex mx, if it is unlocked and not referenced by any condition variable. The mutex becomes invalid for all mutex services (they all return the EINVAL error) except pthread_mutex_init().

Parameters:

mx

the mutex to be destroyed.

Returns:

0 on success,

an error number if:

• EINVAL, the mutex mx is invalid;
• EPERM, the mutex is not process-shared and does not belong to the current process;
• EBUSY, the mutex is locked, or used by a condition variable.

See also:

Specification.

int pthread_mutex_init	(	pthread_mutex_t *	mx,
		const pthread_mutexattr_t *	attr
	)

Initialize a mutex.

This services initializes the mutex mx, using the mutex attributes object attr. If attr is NULL, default attributes are used (see pthread_mutexattr_init()).

Parameters:

	mx	the mutex to be initialized;
	attr	the mutex attributes object.

Returns:

0 on success,

an error number if:

• EINVAL, the mutex attributes object attr is invalid or uninitialized;
• EBUSY, the mutex mx was already initialized;
• ENOMEM, insufficient memory exists in the system heap to initialize the mutex, increase CONFIG_XENO_OPT_SYS_HEAPSZ.

See also:

Specification.

int pthread_mutex_lock

(

pthread_mutex_t *

mx

)

Lock a mutex.

This service attempts to lock the mutex mx. If the mutex is free, it becomes locked. If it was locked by another thread than the current one, the current thread is suspended until the mutex is unlocked. If it was already locked by the current mutex, the behaviour of this service depends on the mutex type :

• for mutexes of the PTHREAD_MUTEX_NORMAL type, this service deadlocks;
• for mutexes of the PTHREAD_MUTEX_ERRORCHECK type, this service returns the EDEADLK error number;
• for mutexes of the PTHREAD_MUTEX_RECURSIVE type, this service increments the lock recursion count and returns 0.

Parameters:

mx

the mutex to be locked.

Returns:

0 on success

an error number if:

• EPERM, the caller context is invalid;
• EINVAL, the mutex mx is invalid;
• EPERM, the mutex is not process-shared and does not belong to the current process;
• EDEADLK, the mutex is of the PTHREAD_MUTEX_ERRORCHECK type and was already locked by the current thread;
• EAGAIN, the mutex is of the PTHREAD_MUTEX_RECURSIVE type and the maximum number of recursive locks has been exceeded.

Valid contexts:

• Xenomai kernel-space thread;
• Xenomai user-space thread (switches to primary mode).

See also:

Specification.

int pthread_mutex_timedlock	(	pthread_mutex_t *	mx,
		const struct timespec *	to
	)

Attempt, during a bounded time, to lock a mutex.

This service is equivalent to pthread_mutex_lock(), except that if the mutex mx is locked by another thread than the current one, this service only suspends the current thread until the timeout specified by to expires.

Parameters:

	mx	the mutex to be locked;
	to	the timeout, expressed as an absolute value of the CLOCK_REALTIME clock.

Returns:

0 on success;

an error number if:

• EPERM, the caller context is invalid;
• EINVAL, the mutex mx is invalid;
• EPERM, the mutex is not process-shared and does not belong to the current process;
• ETIMEDOUT, the mutex could not be locked and the specified timeout expired;
• EDEADLK, the mutex is of the PTHREAD_MUTEX_ERRORCHECK type and the mutex was already locked by the current thread;
• EAGAIN, the mutex is of the PTHREAD_MUTEX_RECURSIVE type and the maximum number of recursive locks has been exceeded.

Valid contexts:

• Xenomai kernel-space thread;
• Xenomai user-space thread (switches to primary mode).

See also:

Specification.

int pthread_mutex_trylock

(

pthread_mutex_t *

mx

)

Attempt to lock a mutex.

This service is equivalent to pthread_mutex_lock(), except that if the mutex mx is locked by another thread than the current one, this service returns immediately.

Parameters:

mx

the mutex to be locked.

Returns:

0 on success;

an error number if:

• EPERM, the caller context is invalid;
• EINVAL, the mutex is invalid;
• EPERM, the mutex is not process-shared and does not belong to the current process;
• EBUSY, the mutex was locked by another thread than the current one;
• EAGAIN, the mutex is recursive, and the maximum number of recursive locks has been exceeded.

Valid contexts:

• Xenomai kernel-space thread,
• Xenomai user-space thread (switches to primary mode).

See also:

Specification.

int pthread_mutex_unlock

(

pthread_mutex_t *

mx

)

Unlock a mutex.

This service unlocks the mutex mx. If the mutex is of the PTHREAD_MUTEX_RECURSIVE type and the locking recursion count is greater than one, the lock recursion count is decremented and the mutex remains locked.

Attempting to unlock a mutex which is not locked or which is locked by another thread than the current one yields the EPERM error, whatever the mutex type attribute.

Parameters:

mx

the mutex to be released.

Returns:

0 on success;

an error number if:

• EPERM, the caller context is invalid;
• EINVAL, the mutex mx is invalid;
• EPERM, the mutex was not locked by the current thread.

Valid contexts:

• Xenomai kernel-space thread,
• kernel-space cancellation cleanup routine,
• Xenomai user-space thread (switches to primary mode),
• user-space cancellation cleanup routine.

See also:

Specification.

int pthread_mutexattr_destroy

(

pthread_mutexattr_t *

attr

)

Destroy a mutex attributes object.

This service destroys the mutex attributes object attr. The object becomes invalid for all mutex services (they all return EINVAL) except pthread_mutexattr_init().

Parameters:

attr

the initialized mutex attributes object to be destroyed.

Returns:

0 on success;

an error number if:

• EINVAL, the mutex attributes object attr is invalid.

See also:

Specification.

int pthread_mutexattr_getprotocol	(	const pthread_mutexattr_t *	attr,
		int *	proto
	)

Get the protocol attribute from a mutex attributes object.

This service stores, at the address proto, the value of the protocol attribute in the mutex attributes object attr.

The protcol attribute may only be one of PTHREAD_PRIO_NONE or PTHREAD_PRIO_INHERIT. See pthread_mutexattr_setprotocol() for the meaning of these two constants.

Parameters:

	attr	an initialized mutex attributes object;
	proto	address where the value of the protocol attribute will be stored on success.

Returns:

0 on success,

an error number if:

• EINVAL, the proto address is invalid;
• EINVAL, the mutex attributes object attr is invalid.

See also:

Specification.

int pthread_mutexattr_getpshared	(	const pthread_mutexattr_t *	attr,
		int *	pshared
	)

Get the process-shared attribute of a mutex attributes object.

This service stores, at the address pshared, the value of the pshared attribute in the mutex attributes object attr.

The pashared attribute may only be one of PTHREAD_PROCESS_PRIVATE or PTHREAD_PROCESS_SHARED. See pthread_mutexattr_setpshared() for the meaning of these two constants.

Parameters:

	attr	an initialized mutex attributes object;
	pshared	address where the value of the pshared attribute will be stored on success.

Returns:

0 on success;

an error number if:

• EINVAL, the pshared address is invalid;
• EINVAL, the mutex attributes object attr is invalid.

See also:

Specification.

int pthread_mutexattr_gettype	(	const pthread_mutexattr_t *	attr,
		int *	type
	)

Get the mutex type attribute from a mutex attributes object.

This service stores, at the address type, the value of the type attribute in the mutex attributes object attr.

See pthread_mutex_lock() and pthread_mutex_unlock() documentations for a description of the values of the type attribute and their effect on a mutex.

Parameters:

	attr	an initialized mutex attributes object,
	type	address where the type attribute value will be stored on success.

Returns:

0 on sucess,

an error number if:

• EINVAL, the type address is invalid;
• EINVAL, the mutex attributes object attr is invalid.

See also:

Specification.

int pthread_mutexattr_init

(

pthread_mutexattr_t *

attr

)

Initialize a mutex attributes object.

This services initializes the mutex attributes object attr with default values for all attributes. Default value are :

• for the type attribute, PTHREAD_MUTEX_NORMAL;
• for the protocol attribute, PTHREAD_PRIO_NONE;
• for the pshared attribute, PTHREAD_PROCESS_PRIVATE.

If this service is called specifying a mutex attributes object that was already initialized, the attributes object is reinitialized.

Parameters:

attr

the mutex attributes object to be initialized.

Returns:

0 on success;

an error number if:

• ENOMEM, the mutex attributes object pointer attr is NULL.

See also:

Specification.

int pthread_mutexattr_setprotocol	(	pthread_mutexattr_t *	attr,
		int	proto
	)

Set the protocol attribute of a mutex attributes object.

This service set the type attribute of the mutex attributes object attr.

Parameters:

	attr	an initialized mutex attributes object,
	proto	value of the protocol attribute, may be one of: PTHREAD_PRIO_NONE, meaning that a mutex created with the attributes object attr will not follow any priority protocol; PTHREAD_PRIO_INHERIT, meaning that a mutex created with the attributes object attr, will follow the priority inheritance protocol.

The value PTHREAD_PRIO_PROTECT (priority ceiling protocol) is unsupported.

Returns:

0 on success,

an error number if:

• EINVAL, the mutex attributes object attr is invalid;
• ENOTSUP, the value of proto is unsupported;
• EINVAL, the value of proto is invalid.

See also:

Specification.

int pthread_mutexattr_setpshared	(	pthread_mutexattr_t *	attr,
		int	pshared
	)

Set the process-shared attribute of a mutex attributes object.

This service set the pshared attribute of the mutex attributes object attr.

Parameters:

	attr	an initialized mutex attributes object.
	pshared	value of the pshared attribute, may be one of: PTHREAD_PROCESS_PRIVATE, meaning that a mutex created with the attributes object attr will only be accessible by threads within the same process as the thread that initialized the mutex; PTHREAD_PROCESS_SHARED, meaning that a mutex created with the attributes object attr will be accessible by any thread that has access to the memory where the mutex is allocated.

Returns:

0 on success,

an error status if:

• EINVAL, the mutex attributes object attr is invalid;
• EINVAL, the value of pshared is invalid.

See also:

Specification.

int pthread_mutexattr_settype	(	pthread_mutexattr_t *	attr,
		int	type
	)

Set the mutex type attribute of a mutex attributes object.

This service set the type attribute of the mutex attributes object attr.

See pthread_mutex_lock() and pthread_mutex_unlock() documentations for a description of the values of the type attribute and their effect on a mutex.

The PTHREAD_MUTEX_DEFAULT default type is the same as PTHREAD_MUTEX_NORMAL. Note that using a Xenomai POSIX skin recursive mutex with a Xenomai POSIX skin condition variable is safe (see pthread_cond_wait() documentation).

Parameters:

	attr	an initialized mutex attributes object,
	type	value of the type attribute.

Returns:

0 on success,

an error number if:

• EINVAL, the mutex attributes object attr is invalid;
• EINVAL, the value of type is invalid for the type attribute.

See also:

Specification.

---