11. Mutex Manager¶

11.1. Introduction¶

The mutex manager implements the functionality required of the mutex manager as defined by POSIX 1003.1b-1996. This standard requires that a compliant operating system provide the facilties to ensure that threads can operate with mutual exclusion from one another and defines the API that must be provided.

The services provided by the mutex manager are:

pthread_mutexattr_init - Initialize a Mutex Attribute Set
pthread_mutexattr_destroy - Destroy a Mutex Attribute Set
pthread_mutexattr_setprotocol - Set the Blocking Protocol
pthread_mutexattr_getprotocol - Get the Blocking Protocol
pthread_mutexattr_setprioceiling - Set the Priority Ceiling
pthread_mutexattr_getprioceiling - Get the Priority Ceiling
pthread_mutexattr_setpshared - Set the Visibility
pthread_mutexattr_getpshared - Get the Visibility
pthread_mutex_init - Initialize a Mutex
pthread_mutex_destroy - Destroy a Mutex
pthread_mutex_lock - Lock a Mutex
pthread_mutex_trylock - Poll to Lock a Mutex
pthread_mutex_timedlock - Lock a Mutex with Timeout
pthread_mutex_unlock - Unlock a Mutex
pthread_mutex_setprioceiling - Dynamically Set the Priority Ceiling
pthread_mutex_getprioceiling - Dynamically Get the Priority Ceiling

11.2. Background¶

11.2.1. Mutex Attributes¶

Mutex attributes are utilized only at mutex creation time. A mutex attribute structure may be initialized and passed as an argument to the mutex_init routine. Note that the priority ceiling of a mutex may be set at run-time.

blocking protcol	is the XXX
priority ceiling	is the XXX
pshared	is the XXX

11.2.2. PTHREAD_MUTEX_INITIALIZER¶

This is a special value that a variable of type pthread_mutex_t may be statically initialized to as shown below:

pthread_mutex_t my_mutex = PTHREAD_MUTEX_INITIALIZER;

This indicates that my_mutex will be automatically initialized by an implicit call to pthread_mutex_init the first time the mutex is used.

Note that the mutex will be initialized with default attributes.

11.3. Operations¶

There is currently no text in this section.

11.4. Services¶

This section details the mutex manager’s services. A subsection is dedicated to each of this manager’s services and describes the calling sequence, related constants, usage, and status codes.

11.4.1. pthread_mutexattr_init - Initialize a Mutex Attribute Set¶

CALLING SEQUENCE:

#include <pthread.h>
int pthread_mutexattr_init(
    pthread_mutexattr_t *attr
);

STATUS CODES:

EINVAL: The attribute pointer argument is invalid.

DESCRIPTION:

The pthread_mutexattr_init routine initializes the mutex attributes object specified by attr with the default value for all of the individual attributes.

NOTES:

XXX insert list of default attributes here.

11.4.2. pthread_mutexattr_destroy - Destroy a Mutex Attribute Set¶

CALLING SEQUENCE:

#include <pthread.h>
    int pthread_mutexattr_destroy(
    pthread_mutexattr_t *attr
);

STATUS CODES:

`EINVAL`	The attribute pointer argument is invalid.
`EINVAL`	The attribute set is not initialized.

DESCRIPTION:

The pthread_mutex_attr_destroy routine is used to destroy a mutex attributes object. The behavior of using an attributes object after it is destroyed is implementation dependent.

NOTES:

NONE

11.4.3. pthread_mutexattr_setprotocol - Set the Blocking Protocol¶

CALLING SEQUENCE:

#include <pthread.h>
int pthread_mutexattr_setprotocol(
    pthread_mutexattr_t *attr,
    int                  protocol
);

STATUS CODES:

`EINVAL`	The attribute pointer argument is invalid.
`EINVAL`	The attribute set is not initialized.
`EINVAL`	The protocol argument is invalid.

DESCRIPTION:

The pthread_mutexattr_setprotocol routine is used to set value of the protocol attribute. This attribute controls the order in which threads waiting on this mutex will receive it.

The protocol can be one of the following:

`PTHREAD_PRIO_NONE`	in which case blocking order is FIFO.
`PTHREAD_PRIO_INHERIT`	in which case blocking order is priority with the priority inheritance protocol in effect.
`PTHREAD_PRIO_PROTECT`	in which case blocking order is priority with the priority ceiling protocol in effect.

NOTES:

There is currently no way to get simple priority blocking ordering with POSIX mutexes even though this could easily by supported by RTEMS.

11.4.4. pthread_mutexattr_getprotocol - Get the Blocking Protocol¶

CALLING SEQUENCE:

#include <pthread.h>
int pthread_mutexattr_getprotocol(
    pthread_mutexattr_t *attr,
    int                 *protocol
);

STATUS CODES:

`EINVAL`	The attribute pointer argument is invalid.
`EINVAL`	The attribute set is not initialized.
`EINVAL`	The protocol pointer argument is invalid.

DESCRIPTION:

The pthread_mutexattr_getprotocol routine is used to obtain the value of the protocol attribute. This attribute controls the order in which threads waiting on this mutex will receive it.

NOTES:

NONE

11.4.5. pthread_mutexattr_setprioceiling - Set the Priority Ceiling¶

CALLING SEQUENCE:

#include <pthread.h>
int pthread_mutexattr_setprioceiling(
    pthread_mutexattr_t *attr,
    int                  prioceiling
);

STATUS CODES:

`EINVAL`	The attribute pointer argument is invalid.
`EINVAL`	The attribute set is not initialized.
`EINVAL`	The prioceiling argument is invalid.

DESCRIPTION:

The pthread_mutexattr_setprioceiling routine is used to set value of the prioceiling attribute. This attribute specifies the priority that is the ceiling for threads obtaining this mutex. Any task obtaining this mutex may not be of greater priority that the ceiling. If it is of lower priority, then its priority will be elevated to prioceiling.

NOTES:

NONE

11.4.6. pthread_mutexattr_getprioceiling - Get the Priority Ceiling¶

CALLING SEQUENCE:

#include <pthread.h>
int pthread_mutexattr_getprioceiling(
    const pthread_mutexattr_t *attr,
    int                       *prioceiling
);

STATUS CODES:

`EINVAL`	The attribute pointer argument is invalid.
`EINVAL`	The attribute set is not initialized.
`EINVAL`	The prioceiling pointer argument is invalid.

DESCRIPTION:

The pthread_mutexattr_getprioceiling routine is used to obtain the value of the prioceiling attribute. This attribute specifies the priority ceiling for this mutex.

NOTES:

NONE

11.4.7. pthread_mutexattr_setpshared - Set the Visibility¶

CALLING SEQUENCE:

#include <pthread.h>
int pthread_mutexattr_setpshared(
    pthread_mutexattr_t *attr,
    int                  pshared
);

STATUS CODES:

`EINVAL`	The attribute pointer argument is invalid.
`EINVAL`	The attribute set is not initialized.
`EINVAL`	The pshared argument is invalid.

DESCRIPTION:

NOTES:

11.4.8. pthread_mutexattr_getpshared - Get the Visibility¶

CALLING SEQUENCE:

#include <pthread.h>
int pthread_mutexattr_getpshared(
    const pthread_mutexattr_t *attr,
    int                       *pshared
);

STATUS CODES:

`EINVAL`	The attribute pointer argument is invalid.
`EINVAL`	The attribute set is not initialized.
`EINVAL`	The pshared pointer argument is invalid.

DESCRIPTION:

NOTES:

11.4.9. pthread_mutex_init - Initialize a Mutex¶

CALLING SEQUENCE:

#include <pthread.h>
int pthread_mutex_init(
    pthread_mutex_t           *mutex,
    const pthread_mutexattr_t *attr
);

STATUS CODES:

`EINVAL`	The attribute set is not initialized.
`EINVAL`	The specified protocol is invalid.
`EAGAIN`	The system lacked the necessary resources to initialize another mutex.
`ENOMEM`	Insufficient memory exists to initialize the mutex.
`EBUSY`	Attempted to reinialize the object reference by mutex, a previously initialized, but not yet destroyed.

DESCRIPTION:

NOTES:

11.4.10. pthread_mutex_destroy - Destroy a Mutex¶

CALLING SEQUENCE:

#include <pthread.h>
    int pthread_mutex_destroy(
    pthread_mutex_t *mutex
);

STATUS CODES:

`EINVAL`	The specified mutex is invalid.
`EBUSY`	Attempted to destroy the object reference by mutex, while it is locked or referenced by another thread.

DESCRIPTION:

NOTES:

11.4.11. pthread_mutex_lock - Lock a Mutex¶

CALLING SEQUENCE:

#include <pthread.h>
int pthread_mutex_lock(
    pthread_mutex_t *mutex
);

STATUS CODES:

`EINVAL`	The specified mutex is invalid.
`EINVAL`	The mutex has the protocol attribute of `PTHREAD_PRIO_PROTECT` and the priority of the calling thread is higher than the current priority ceiling.
`EDEADLK`	The current thread already owns the mutex.

DESCRIPTION:

NOTES:

11.4.12. pthread_mutex_trylock - Poll to Lock a Mutex¶

CALLING SEQUENCE:

#include <pthread.h>
int pthread_mutex_trylock(
    pthread_mutex_t *mutex
);

STATUS CODES:

`EINVAL`	The specified mutex is invalid.
`EINVAL`	The mutex has the protocol attribute of `PTHREAD_PRIO_PROTECT` and the priority of the calling thread is higher than the current priority ceiling.
`EBUSY`	The mutex is already locked.

DESCRIPTION:

NOTES:

11.4.13. pthread_mutex_timedlock - Lock a Mutex with Timeout¶

CALLING SEQUENCE:

#include <pthread.h>
#include <time.h>
int pthread_mutex_timedlock(
    pthread_mutex_t       *mutex,
    const struct timespec *timeout
);

STATUS CODES:

`EINVAL`	The specified mutex is invalid.
`EINVAL`	The nanoseconds field of timeout is invalid.
`EINVAL`	The mutex has the protocol attribute of `PTHREAD_PRIO_PROTECT` and the priority of the calling thread is higher than the current priority ceiling.
`EDEADLK`	The current thread already owns the mutex.
`ETIMEDOUT`	The calling thread was unable to obtain the mutex within the specified timeout period.

DESCRIPTION:

NOTES:

11.4.14. pthread_mutex_unlock - Unlock a Mutex¶

CALLING SEQUENCE:

#include <pthread.h>
int pthread_mutex_unlock(
    pthread_mutex_t *mutex
);

STATUS CODES:

EINVAL

The specified mutex is invalid.

DESCRIPTION:

NOTES:

11.4.15. pthread_mutex_setprioceiling - Dynamically Set the Priority Ceiling¶

CALLING SEQUENCE:

#include <pthread.h>
int pthread_mutex_setprioceiling(
    pthread_mutex_t *mutex,
    int              prioceiling,
    int             *oldceiling
);

STATUS CODES:

`EINVAL`	The oldceiling pointer parameter is invalid.
`EINVAL`	The prioceiling parameter is an invalid priority.
`EINVAL`	The specified mutex is invalid.

DESCRIPTION:

NOTES:

11.4.16. pthread_mutex_getprioceiling - Get the Current Priority Ceiling¶

CALLING SEQUENCE:

#include <pthread.h>
int pthread_mutex_getprioceiling(
    pthread_mutex_t *mutex,
    int             *prioceiling
);

STATUS CODES:

`EINVAL`	The prioceiling pointer parameter is invalid.
`EINVAL`	The specified mutex is invalid.

DESCRIPTION:

NOTES: