Mutual exclusion

Cobalt/POSIX mutual exclusion services. More...

Collaboration diagram for Mutual exclusion:

Functions
int	pthread_mutex_init (pthread_mutex_t *mutex, const pthread_mutexattr_t *attr)
	Initialize a mutex. More...
static int	__attribute__ ((cold))
	Test if a mutex structure contains a valid autoinitializer. More...
int	pthread_mutex_destroy (pthread_mutex_t *mutex)
	Destroy a mutex. More...
int	pthread_mutex_lock (pthread_mutex_t *mutex)
	Lock a mutex. More...
int	pthread_mutex_timedlock (pthread_mutex_t *mutex, const struct timespec *to)
	Attempt, during a bounded time, to lock a mutex. More...
int	pthread_mutex_trylock (pthread_mutex_t *mutex)
	Attempt to lock a mutex. More...
int	pthread_mutex_unlock (pthread_mutex_t *mutex)
	Unlock a mutex. More...
int	pthread_mutex_setprioceiling (pthread_mutex_t *__restrict mutex, int prioceiling, int *__restrict old_ceiling)
	Set a mutex's priority ceiling. More...
int	pthread_mutex_getprioceiling (pthread_mutex_t *__restrict mutex, int *__restrict prioceiling)
	Get a mutex's priority ceiling. 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

Cobalt/POSIX mutual exclusion 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, Cobalt mutexes are of the normal type, use no priority protocol and may not be shared between several processes.

Note that pthread_mutex_init() should be used to initialize a mutex, using the static initializer PTHREAD_MUTEX_INITIALIZER will delay the initialization to the first method called on the mutex and will most likely introduce switches to secondary mode. The documentation (and specifically api-tags) of the mutex services assumes a mutex was explicitly initialised with pthread_mutex_init().

Function Documentation

__attribute__()

static int __attribute__ ( (cold)  )

static

Test if a mutex structure contains a valid autoinitializer.

Returns

the mutex type on success,

-1 if not in supported autoinitializer state

pthread_mutex_destroy()

int pthread_mutex_destroy

(

pthread_mutex_t *

mutex

)

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

mutex

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.

Tags

thread-unrestricted

pthread_mutex_getprioceiling()

int pthread_mutex_getprioceiling	(	pthread_mutex_t *__restrict	mutex,
		int *__restrict	prioceiling
	)

Get a mutex's priority ceiling.

This routine retrieves the priority ceiling value of the specified mutex.

Parameters

mutex	the target mutex.
prioceiling	on success, the current ceiling value is copied to this address.

Returns

0 on success;

an error number if:

• EINVAL, mutex is invalid;
• EINVAL, mutex is not of type PTHREAD_PRIO_PROTECT;

See also

Specification.

Tags

thread-unrestricted

pthread_mutex_init()

int pthread_mutex_init	(	pthread_mutex_t *	mutex,
		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

mutex	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 available from the system heap to initialize the mutex, increase CONFIG_XENO_OPT_SYS_HEAPSZ.
• EAGAIN, insufficient memory available to initialize the mutex, increase CONFIG_XENO_OPT_SHARED_HEAPSZ for a process-shared mutex, or CONFIG_XENO_OPT_PRIVATE_HEAPSZ for a process-private mutex.
• EAGAIN, no registry slot available, check/raise CONFIG_XENO_OPT_REGISTRY_NRSLOTS.
• ENOSYS, attr mentions priority protection (PTHREAD_PRIO_PROTECT), but the C library does not provide pthread_mutexattr_get/setprioceiling().

See also

Specification.

Tags

thread-unrestricted

pthread_mutex_lock()

int pthread_mutex_lock

(

pthread_mutex_t *

mutex

)

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

mutex

the mutex to be locked.

Returns

0 on success

an error number if:

• EPERM, the caller is not allowed to perform the operation;
• 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.

See also

Specification.

Tags

xthread-only, switch-primary

pthread_mutex_setprioceiling()

int pthread_mutex_setprioceiling	(	pthread_mutex_t *__restrict	mutex,
		int	prioceiling,
		int *__restrict	old_ceiling
	)

Set a mutex's priority ceiling.

This routine acquires the specified mutex, then changes the associated priority ceiling value and releases it. prioceiling must be between the values returned by sched_get_priority_min() and sched_get_priority_max(), inclusive.

The Cobalt implementation applies the priority ceiling protocol using the previous ceiling value during this operation. The new priority ceiling will apply next time the mutex transitions from the unlocked to locked state.

Parameters

mutex	the target mutex.
prioceiling	the new ceiling value.
old_ceiling	on success and if this parameter is non-NULL, the previous ceiling value is copied to this address.

Returns

0 on success;

an error number if:

• EPERM, the caller is not allowed to perform the operation;
• EINVAL, mutex is invalid;
• EINVAL, mutex is not of type PTHREAD_PRIO_PROTECT;
• EINVAL, prioceiling is out of range;

See also

Specification.

Tags

xthread-only, switch-primary

Note

If the calling thread's priority is higher than the mutex's new priority ceiling, the operation will nevertheless succeed; the Cobalt core never decreases the effective priority of a thread which locks a priority-protected mutex.

pthread_mutex_timedlock()

int pthread_mutex_timedlock	(	pthread_mutex_t *	mutex,
		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

mutex	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 is not allowed to perform the operation;
• 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.

See also

Specification.

Tags

xthread-only, switch-primary

pthread_mutex_trylock()

int pthread_mutex_trylock

(

pthread_mutex_t *

mutex

)

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

mutex

the mutex to be locked.

Returns

0 on success;

an error number if:

• EPERM, the caller is not allowed to perform the operation;
• 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.

See also

Specification.

Tags

xthread-only, switch-primary

pthread_mutex_unlock()

int pthread_mutex_unlock

(

pthread_mutex_t *

mutex

)

Unlock a mutex.

This service unlocks the mutex. If mutex is of the PTHREAD_MUTEX_RECURSIVE 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

mutex

the mutex to be released.

Returns

0 on success;

an error number if:

• EPERM, the caller is not allowed to perform the operation;
• EINVAL, the mutex mutex is invalid;
• EPERM, the mutex was not locked by the current thread.

See also

Specification.

Tags

xthread-only, switch-primary

pthread_mutexattr_destroy()

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.

Tags

thread-unrestricted

pthread_mutexattr_getprotocol()

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 be one of PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT. See pthread_mutexattr_setprotocol() for the meaning of these 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.

Tags

thread-unrestricted

pthread_mutexattr_getpshared()

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.

Tags

thread-unrestricted

pthread_mutexattr_gettype()

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() 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.

Tags

thread-unrestricted

pthread_mutexattr_init()

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.

Tags

thread-unrestricted

pthread_mutexattr_setprotocol()

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. PTHREAD_PRIO_PROTECT, meaning that a mutex created with the attributes object attr, will follow the priority protect protocol.

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.

Tags

thread-unrestricted

pthread_mutexattr_setpshared()

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.

Tags

thread-unrestricted

pthread_mutexattr_settype()

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() 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 recursive Cobalt mutex with a Cobalt 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.

Tags

thread-unrestricted