Set Mutex Attribute's Protocol

pthread_mutexattr_setprotocol(3THR)

pthread_mutexattr_setprotocol(3THR) sets the protocol attribute of a mutex attribute object.

#include <pthread.h>

int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr, int protocol);

attr points to a mutex attribute object created by an earlier call to pthread_mutexattr_init().

protocol defines the protocol applied to the mutex attribute object.

The value of protocol, defined in pthread.h, can be: PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT, or PTHREAD_PRIO_PROTECT.

• PTHREAD_PRIO_NONE

  A thread's priority and scheduling are not affected by the mutex ownership.

• PTHREAD_PRIO_INHERIT

  This protocol value affects a thread's (such as thrd1) priority and scheduling when higher-priority threads block on one or more mutexes owned by thrd1 where those mutexes are initialized with PTHREAD_PRIO_INHERIT. thrd1 runs with the higher of its priority or the highest priority of any thread waiting on any of the mutexes owned by thrd1.

  If thrd1 blocks on a mutex owned by another thread, thrd3, the same priority inheritance effect recursively propagates to thrd3.

  Use PTHREAD_PRIO_INHERIT to avoid priority inversion. Priority inversion occurs when a low-priority thread holds a lock that a higher-priority thread wants. Because the higher-priority thread cannot continue until the lower-priority thread releases the lock, each thread is treated as if it had the inverse of its intended priority.

  If the symbol _POSIX_THREAD_PRIO_INHERIT is defined, for a mutex initialized with the protocol attribute value PTHREAD_PRIO_INHERIT, the following actions occur in the Solaris Operating Environment when the owner of that mutex dies:

  ---

  Note –

  The behavior on owner death depends on the value of the robustness argument of pthread_mutexattr_setrobust_np().

  ---

  • The mutex is unlocked.

  • The next owner of the mutex acquires it with an error return of EOWNERDEAD.

  • The next owner of the mutex should try to make the state protected by the mutex consistent—the state might have been left inconsistent when the previous owner died. If the owner is successful in making the state consistent, call pthread_mutex_init() for the mutex and unlock the mutex.

    ---

    Note –

    If pthread_mutex_init() is called on a previously initialized, but not yet destroyed mutex, the mutex is not reinitialized.

    ---

  • If the owner is unable to make the state consistent, do not call pthread_mutex_init(), but unlock the mutex. In this event, all waiters will be woken up and all subsequent calls to pthread_mutex_lock() will fail to acquire the mutex and return an error code of ENOTRECOVERABLE. You can now make the mutex state consistent by calling pthread_mutex_destroy() to uninitialize the mutex and calling pthread_mutex_init() to reinitialize it.

  • If the thread that acquired the lock with EOWNERDEAD dies, the next owner acquires the lock with an error code of EOWNERDEAD.

• PTHREAD_PRIO_PROTECT

  This protocol value affects a thread's (such as thrd2) priority and scheduling when the thread owns one or more mutexes initialized with PTHREAD_PRIO_PROTECT. thrd2 runs with the higher of its priority or the highest-priority ceiling of all mutexes it owns. Higher-priority threads blocked on any of the mutexes, owned by thrd2, have no effect on the scheduling of thrd2.

When a thread owns a mutex that is initialized with PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT, and that thread's original priority changes, such as by a call to sched_setparam(), the scheduler does not move the thread to the tail of the scheduling queue at it's new priority. Similarly, when a thread unlocks a mutex that is initialized with PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT, and that thread's original priority changes, the scheduler does not move the thread to the tail of the scheduling queue at it's new priority.

If a thread simultaneously owns several mutexes initialized with a mix of PTHREAD_PRIO_INHERIT and PTHREAD_PRIO_PROTECT, it executes at the highest priority obtained by either of these protocols.

Return Values

On successful completion, pthread_mutexattr_setprotocol() returns 0. Any other return value indicates that an error occurred.

If either of the following conditions occurs, pthread_mutexattr_setprotocol() fails and returns the corresponding value.

ENOSYS

Neither of the options _POSIX_THREAD_PRIO_INHERIT and _POSIX_THREAD_PRIO_PROTECT is defined and the implementation does not support the function.

ENOTSUP

The value specified by protocol is an unsupported value.

If either of the following conditions occurs, pthread_mutexattr_setprotocol() might fail and return the corresponding value.

EINVAL

The value specified by attr or protocol is not valid.

EPERM

The caller does not have the privilege to perform the operation.