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

SEE ALSO
     pthread_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).