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:
|
The attribute pointer argument is invalid. |
|
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:
|
The attribute pointer argument is invalid. |
|
The attribute set is not initialized. |
|
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:
|
in which case blocking order is FIFO. |
|
in which case blocking order is priority with the priority inheritance protocol in effect. |
|
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:
|
The attribute pointer argument is invalid. |
|
The attribute set is not initialized. |
|
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:
|
The attribute pointer argument is invalid. |
|
The attribute set is not initialized. |
|
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:
|
The attribute pointer argument is invalid. |
|
The attribute set is not initialized. |
|
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.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:
|
The attribute set is not initialized. |
|
The specified protocol is invalid. |
|
The system lacked the necessary resources to initialize another mutex. |
|
Insufficient memory exists to initialize the mutex. |
|
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:
|
The specified mutex is invalid. |
|
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:
|
The specified mutex is invalid. |
|
The mutex has the protocol attribute of |
|
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:
|
The specified mutex is invalid. |
|
The mutex has the protocol attribute of |
|
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:
|
The specified mutex is invalid. |
|
The nanoseconds field of timeout is invalid. |
|
The mutex has the protocol attribute of |
|
The current thread already owns the mutex. |
|
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:
|
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:
|
The oldceiling pointer parameter is invalid. |
|
The prioceiling parameter is an invalid priority. |
|
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:
|
The prioceiling pointer parameter is invalid. |
|
The specified mutex is invalid. |
DESCRIPTION:
NOTES: