pthread_mutexattr_getprotocol(3T)

NAME

pthread_mutexattr_getprotocol(), pthread_mutexattr_setprotocol(), pthread_mutexattr_getprioceiling(), pthread_mutexattr_setprioceiling() — get and set the protocol and prioceiling attributes

SYNOPSIS

#include <pthread.h>

int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr, int prioceiling);

int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *__restrict attr, int *__restrict prioceiling);

int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr, int protocol);

int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *__restrict attr, int *__restrictprotocol);

PARAMETERS

attr: Pointer to the mutex attributes object whose attributes are to be set/retrieved.
prioceiling: This parameter either specifies the new value of the prioceiling attribute (set function) or points to the memory location where the prioceiling attribute of attr is to be returned (get function).
protocol: This parameter either specifies the new value of the protocol attribute (set function) or points to the memory location where the protocol attribute of attr is to be returned (get function).

DESCRIPTION

Be sure to check for the definitions of _POSIX_THREAD_PRIO_PROTECT and _POSIX_THREAD_PRIO_INHERIT before using these functions. Not all systems will support these functions.

The attributes object attr must have previously been initialized with the function pthread_mutexattr_init() before these functions are called.

ATTRIBUTE: protocol

Mutexes can be initialized with a priority protocol to help avoid or minimize the priority inversion that can be caused by locked mutexes. The protocol attribute in a mutex attributes object describes the priority protocol to be used when the mutex is locked by a thread. The legal values for the protocol attribute are:

PTHREAD_PRIO_NONE

A thread's scheduling priority is not changed when it locks this type of mutex.

PTHREAD_PRIO_PROTECT

These types of mutexes have an associated priority value in the prioceiling attribute. When a thread locks a mutex of this type, its scheduling priority will be changed to be the value contained in the prioceiling attribute. The value of prioceiling must be higher than the locking thread's scheduling priority. When the mutex is unlocked, the thread's previous scheduling priority will be restored.

If a thread owns several mutexes of this type, its scheduling priority will be changed to the higher of all the prioceiling attributes for all mutexes of this type that it owns.

PTHREAD_PRIO_INHERIT

When a thread must block waiting for a mutex of this type, the system will change the scheduling priority of the thread that owns the mutex to be the higher of its own priority or the priority of the highest priority thread blocked on the mutex. When the mutex is unlocked, the thread's previous scheduling priority will be restored.

If a thread owns one or more mutexes having the protocol attribute value of PTHREAD_PRIO_PROTECT or PTHREAD_PRIO_INHERIT, the thread will not be moved to the tail of its priority list if its original priority is changed or when it unlocks the mutex(es).

If a thread owns mutexes of different priority protocols, it will execute at the highest of the priorities that would be obtained by each of these protocols. If this thread becomes blocked on another mutex, the priority behavior is recursive and is passed on to the thread that owns the mutex on which this thread is blocked.

POSIX.1c does not define a default value for the protocol attribute. On HP-UX, the default value is PTHREAD_PRIO_NONE.

pthread_mutexattr_setprotocol() is used to set the protocol attribute in the initialized attributes object attr. The new value of the protocol attribute of attr is set to the value specified in the protocol parameter.

pthread_mutexattr_getprotocol() retrieves the value of the protocol attribute from the mutex attributes object attr. The value of the protocol attribute of attr is returned in the protocol parameter.

ATTRIBUTE: prioceiling

If the protocol attribute has a value of PTHREAD_PRIO_PROTECT, the prioceiling attribute indicates the priority ceiling of the mutex. Otherwise, this attribute is not used when the mutex is initialized.

The priority values that are valid for this attribute are the same values that are valid for the SCHED_FIFO scheduling policy.

POSIX.1c does not define a default value for the prioceiling attribute. On HP-UX, the default value is the minimum priority value for the SCHED_FIFO scheduling policy.

pthread_mutexattr_setprioceiling() is used to set the prioceiling attribute in the initialized attributes object attr. The new value of the prioceiling attribute of attr is set to the value specified in the prioceiling parameter.

pthread_mutexattr_getprioceiling() retrieves the value of the prioceiling attribute from the mutex attributes object attr. The value of the prioceiling attribute of attr is returned in the prioceiling parameter.

RETURN VALUE

Upon successful completion, pthread_mutexattr_setprioceiling(), pthread_mutexattr_getprioceiling(), pthread_mutexattr_setprotocol(), and pthread_mutexattr_getprotocol() return zero. Otherwise, an error number is returned to indicate the error (the errno variable is not set).

ERRORS

If any of the following occur, the pthread_mutexattr_setprioceiling(), pthread_mutexattr_getprioceiling(), pthread_mutexattr_setprotocol(), and pthread_mutexattr_getprotocol() functions return the corresponding error number:

ENOSYS: _POSIX_THREAD_PRIO_PROTECT is not defined and these functions are not supported.
ENOTSUP: protocol contains an unsupported value.

For each of the following conditions, if the condition is detected, the pthread_mutexattr_setprioceiling(), pthread_mutexattr_getprioceiling(), pthread_mutexattr_setprotocol(), and pthread_mutexattr_getprotocol() functions return the corresponding error number:

EINVAL: The value specified by attr, prioceiling, or protocol is invalid.
EPERM: The caller does not have the appropriate privilege to set the priority ceiling or priority protocol to the specified values.

AUTHOR

pthread_mutexattr_setprioceiling(), pthread_mutexattr_getprioceiling(), pthread_mutexattr_setprotocol(), and pthread_mutexattr_getprotocol() were derived from the IEEE POSIX P1003.1c standard.

STANDARDS CONFORMANCE

pthread_mutexattr_setprioceiling(): POSIX 1003.1c.
pthread_mutexattr_getprioceiling(): POSIX 1003.1c.
pthread_mutexattr_setprotocol(): POSIX 1003.1c.
pthread_mutexattr_getprotocol(): POSIX 1003.1c.