Manual Pages for UNIX Operating System command usage for man pthread_mutexattr_getprotocol

Standard C Library Functions    pthread_mutexattr_getprotocol(3C)



NAME
     pthread_mutexattr_getprotocol, pthread_mutexattr_setprotocol
     - get or set protocol attribute of mutex attribute object

SYNOPSIS
     cc -mt [ flag... ] file... -lpthread [ library... ]
     #include 

     int pthread_mutexattr_getprotocol(
          const pthread_mutexattr_t *restrict attr,
          int *restrict protocol);


     int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr,
          int protocol);


DESCRIPTION
     The           pthread_mutexattr_setprotocol()            and
     pthread_mutexattr_getprotocol() functions, respectively, set
     and get the protocol attribute of a mutex  attribute  object
     pointed  to  by  attr,  which  was previously created by the
     pthread_mutexattr_init() function.


     The protocol attribute defines the protocol to  be  followed
     in  utilizing  mutexes.  The value of protocol may be one of
     PTHREAD_PRIO_NONE,         PTHREAD_PRIO_INHERIT,          or
     PTHREAD_PRIO_PROTECT,   which  are  defined  by  the  header
     .


     When a thread owns a mutex with the  PTHREAD_PRIO_NONE  pro-
     tocol   attribute,  its  priority  and  scheduling  are  not
     affected by its mutex ownership.


     When a thread is blocking higher priority threads because of
     owning  one  or  more mutexes with the  PTHREAD_PRIO_INHERIT
     protocol attribute, it executes at the higher of its  prior-
     ity  or  the priority of the highest priority thread waiting
     on any of the mutexes owned by this thread  and  initialized
     with this protocol.


     When a thread owns one or more mutexes initialized with  the
     PTHREAD_PRIO_PROTECT  protocol, it executes at the higher of
     its priority or the highest of the priority ceilings of  all
     the  mutexes  owned by this thread and initialized with this
     attribute, regardless of whether other threads  are  blocked
     on any of these mutexes.




SunOS 5.11           Last change: 5 Feb 2008                    1






Standard C Library Functions    pthread_mutexattr_getprotocol(3C)



     While a thread is holding a mutex that has been  initialized
     with  the PRIO_INHERIT or  PRIO_PROTECT protocol attributes,
     it will not be subject to being moved to  the  tail  of  the
     scheduling  queue at its priority in the event that its ori-
     ginal  priority  is  changed,  such  as   by   a   call   to
     sched_setparam().  Likewise,  when  a thread unlocks a mutex
     that  has  been  initialized  with   the   PRIO_INHERIT   or
     PRIO_PROTECT  protocol attributes, it will not be subject to
     being moved to the tail  of  the  scheduling  queue  at  its
     priority in the event that its original priority is changed.


     If a thread simultaneously owns several mutexes  initialized
     with  different protocols, it will execute at the highest of
     the priorities that it would have obtained by each of  these
     protocols.


     If a thread makes a call to pthread_mutex_lock() for a mutex
     that   was   initialized   with   the   protocol   attribute
     PTHREAD_PRIO_INHERIT, and  if  the  calling  thread  becomes
     blocked  because  the mutex is owned by another thread, then
     the owner thread inherits the priority level of the  calling
     thread  for  as  long  as it continues to own the mutex. The
     implementation updates its execution priority to the maximum
     of  its  assigned priority and all its inherited priorities.
     Furthermore, if this owner thread becomes blocked on another
     mutex,  the  same  priority  inheritance effect will be pro-
     pagated to the other owner thread, in a recursive manner.


     A  thread   that   uses   mutexes   initialized   with   the
     PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT protocol attri-
     bute values should  have  its  scheduling  policy  equal  to
     SCHED_FIFO  or  SCHED_RR (see pthread_attr_getschedparam(3C)
     and pthread_getschedparam(3C)).


     If a thread with scheduling policy equal to SCHED_OTHER uses
     a   mutex   initialized  with  the  PTHREAD_PRIO_INHERIT  or
     PTHREAD_PRIO_PROTECT protocol attribute value, the effect on
     the thread's scheduling and priority is unspecified.


     The              _POSIX_THREAD_PRIO_INHERIT              and
     _POSIX_THREAD_PRIO_PROTECT  options  are designed to provide
     features to solve  priority  inversion  due  to  mutexes.  A
     priority  inheritance  or priority ceiling mutex is designed
     to minimize the dispatch latency of a high  priority  thread
     when  a  low  priority thread is holding a mutex required by
     the high priority thread.  This is a specific need  for  the
     realtime application domain.



SunOS 5.11           Last change: 5 Feb 2008                    2






Standard C Library Functions    pthread_mutexattr_getprotocol(3C)



     Threads created by realtime applications  need  to  be  such
     that  their  priorities can influence their access to system
     resources (CPU resources, at least), in competition with all
     threads running on the system.

RETURN VALUES
     Upon          successful           completion,           the
     pthread_mutexattr_getprotocol()                          and
     pthread_mutexattr_setprotocol() functions return  0.  Other-
     wise, an error number is returned to indicate the error.

ERRORS
     The            pthread_mutexattr_getprotocol()           and
     pthread_mutexattr_setprotocol() functions will fail if:

     EINVAL     The value specified by attr is NULL.


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


     ENOTSUP    The value specified by protocol is an unsupported
                value.



     The           pthread_mutexattr_getprotocol()            and
     pthread_mutexattr_setprotocol() functions may fail if:

     EINVAL    The  value  specified  by  attr  or  protocol   is
               invalid.


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


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:













SunOS 5.11           Last change: 5 Feb 2008                    3






Standard C Library Functions    pthread_mutexattr_getprotocol(3C)



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|
    | Standard                    | See standards(5).           |
    |_____________________________|_____________________________|


SEE ALSO
     pthread_attr_getschedparam(3C),      pthread_mutex_init(3C),
     pthread_mutexattr_init(3C),              sched_setparam(3C),
     sched_setscheduler(3C), attributes(5), standards(5)








































SunOS 5.11           Last change: 5 Feb 2008                    4