Mutex services. More...

Collaboration diagram for Mutex services.:

Functions
int	pthread_mutex_init (pthread_mutex_t mx, const pthread_mutexattr_t attr)
	Initialize a mutex. More...

int	pthread_mutex_destroy (pthread_mutex_t *mx)
	Destroy a mutex. More...

int	pthread_mutex_trylock (pthread_mutex_t *mx)
	Attempt to lock a mutex. More...

int	pthread_mutex_lock (pthread_mutex_t *mx)
	Lock a mutex. More...

int	pthread_mutex_timedlock (pthread_mutex_t mx, const struct timespec to)
	Attempt, during a bounded time, to lock a mutex. More...

int	pthread_mutex_unlock (pthread_mutex_t *mx)
	Unlock a mutex. More...

int	pthread_mutexattr_init (pthread_mutexattr_t *attr)
	Initialize a mutex attributes object. More...

int	pthread_mutexattr_destroy (pthread_mutexattr_t *attr)
	Destroy a mutex attributes object. More...

int	pthread_mutexattr_gettype (const pthread_mutexattr_t attr, int type)
	Get the mutex type attribute from a mutex attributes object. More...

int	pthread_mutexattr_settype (pthread_mutexattr_t *attr, int type)
	Set the mutex type attribute of a mutex attributes object. More...

int	pthread_mutexattr_getprotocol (const pthread_mutexattr_t attr, int proto)
	Get the protocol attribute from a mutex attributes object. More...

int	pthread_mutexattr_setprotocol (pthread_mutexattr_t *attr, int proto)
	Set the protocol attribute of a mutex attributes object. More...

int	pthread_mutexattr_getpshared (const pthread_mutexattr_t attr, int pshared)
	Get the process-shared attribute of a mutex attributes object. More...

int	pthread_mutexattr_setpshared (pthread_mutexattr_t *attr, int pshared)
	Set the process-shared attribute of a mutex attributes object. More...

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.

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.

References XNBREAK, XNRMID, xnsynch_acquire(), and XNTIMEO.

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.
EAGAIN, insufficient memory exists in the semaphore heap to initialize the mutex, increase CONFIG_XENO_OPT_GLOBAL_SEM_HEAPSZ for a process-shared mutex, or CONFG_XENO_OPT_SEM_HEAPSZ for a process-private mutex.

See also: Specification.

References xnheap_alloc(), and xnheap_free().

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.

References XNOTHER.

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.

References xnpod_schedule(), and xnsynch_release().

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.

Functions

Detailed Description

Function Documentation