11. Mutex Manager¶

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.

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.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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

DESCRIPTION:

NOTES: