pthread_mutexattr_setprotocol(3P)pthread_mutexattr_setprotocol(3P)NAME
pthread_mutexattr_setprotocol, pthread_mutexattr_getprotocol,
pthread_mutexattr_setprioceiling, pthread_mutexattr_getprioceiling -
set/get a mutex attribute object's priority and protocol
C SYNOPSIS
#include <pthread.h>
int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr,
int protocol);
int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *attr,
int *oprotocol);
int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr,
int prioceiling);
int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *attr,
int *oprioceiling);
DESCRIPTION
These functions manipulate a mutex attribute object referenced by attr
which has been previously created by pthread_mutexattr_init().
The function pthread_mutexattr_setprotocol() defines the thread priority
protocol to be followed when acquiring and holding mutexes. The protocol
value may be one of PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT,
PTHREAD_PRIO_PROTECT, PTHREAD_PRIO_THREAD_NP, or PTHREAD_PRIO_SYSTEM_NP.
The function pthread_mutexattr_getprotocol() stores into the memory
referenced by oprotocol the thread priority protocol associated with the
named mutex attribute object. The default protocol is PTHREAD_PRIO_NONE.
When a thread owns a mutex with the PTHREAD_PRIO_NONE protocol attribute,
the thread's priority and scheduling are not affected by its mutex
ownership.
When a thread owns one or more mutexes that have been initialized with
the PTHREAD_PRIO_PROTECT or PTHREAD_PRIO_INHERIT protocol, it will
execute at the higher of its current priority or the highest priority
associated with any owned mutex.
For mutexes initialized with the PTHREAD_PRIO_INHERIT protocol, the
priority associated with the owned mutex is the highest priority of any
thread waiting to acquire the mutex. (Note that if the thread that owns
a mutex with the PTHREAD_PRIO_INHERIT protocol becomes blocked on another
mutex with the PTHREAD_PRIO_INHERIT, protocol, priority inheritance will
be propagated to the owning thread of this other mutex.)
For mutexes initialized with the PTHREAD_PRIO_PROTECT protocol, the
priority associated with the mutex is set either by calls to
pthread_mutex_setprioceiling() or by call to
pthread_mutexattr_setprioceiling() on the mutex attribute object that was
Page 1
pthread_mutexattr_setprotocol(3P)pthread_mutexattr_setprotocol(3P)
used to initialized the mutex. For pthread_mutexattr_setprioceiling(),
the values of prioceiling must be within the values returned by
sched_get_priority_min() and sched_get_priority_max() for the SCHED_FIFO
policy. The function pthread_mutexattr_getprioceiling() stores into the
memory referenced by oprioceiling the priority associated with the named
mutex attribute object; the default priority is the return value from
sched_get_priority_min(). Note that a call to pthread_mutex_lock() will
fail if the mutex protocol attribute is PTHREAD_PRIO_PROTECT and the
priority associated with the mutex is less than the calling thread's
priority.
Mutexes initialized with the PTHREAD_PRIO_THREAD_NP protocol when locked
by a system scope pthread allow that pthread not to be preempted by any
other pthread within the same process until the mutex is released. The
protocol is a very low overhead alternative to priority ceiling and
priority inheritance mutexes. Mutexes initialized with the
PTHREAD_PRIO_SYSTEM_NP protocol are similar but in addition to providing
thread non-preemption they allow lockers to avoid being preempted by any
other user process or kernel thread in the system. A pthread may only
simultaneously lock up to 255 of these system non-preemption mutexes and
thread non-preemption mutexes. Each lock of a recursive mutex with one
of these protocols affects the count as well. The results of locking one
of these mutexes with a non - system scope non - real-time scheduled
pthread are undefined.
Pthreads holding a thread or system non-preemption mutex may avoid up to
a configurable number of preemption attempts by the operating system.
This value is set by the nonpreempts systune. For values 0 - 255 the
pthread may avoid up to that many preemptions before it must voluntarily
or involuntarily yield the processor. A value of 256 allows it to avoid
preemption indefinitely.
NOTES
Priority inheritance and thread nonpreemption are not supported for
process-shared mutexes; all other protocols are supported, including
priority ceiling. Neither priority inheritance nor priority ceiling is
supported for PTHREAD_MUTEX_SPINBLOCK_NP type mutexes.
DIAGNOSTICS
All of the mutex attribute protocol functions return zero on success;
otherwise, an error number is returned:
[EINVAL] The value specified by protocol or prioceiling is invalid.
[EINVAL] The value specified by protocol is PTHREAD_PRIO_INHERIT
and the process-shared attribute is set to
PTHREAD_PROCESS_SHARED.
[EINVAL] The routine has been called for a mutex of type
PTHREAD_MUTEX_SPINBLOCK_NP and the protocol specified was
PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT.
Page 2
pthread_mutexattr_setprotocol(3P)pthread_mutexattr_setprotocol(3P)SEE ALSOpthread_mutex_lock(3P), pthread_mutex_setprioceiling(3P),
pthread_mutexattr_settype(3P), pthread_mutexattr_init(3P),
sched_get_priority_min(3C), sched_get_priority_max(3C).
Page 3
