Standard C Library Functions pthreadmutexattrgetprotocol(3C)
NAME
pthreadmutexattrgetprotocol, pthreadmutexattrsetprotocol
- get or set protocol attribute of mutex attribute object
SYNOPSIS
cc -mt [ flag... ] file... -lpthread [ library... ]
#include
int pthreadmutexattrgetprotocol(
const pthreadmutexattrt *restrict attr,
int *restrict protocol);
int pthreadmutexattrsetprotocol(pthreadmutexattrt *attr,
int protocol);
DESCRIPTION
The pthreadmutexattrsetprotocol() and
pthreadmutexattrgetprotocol() functions, respectively, set
and get the protocol attribute of a mutex attribute object
pointed to by attr, which was previously created by the
pthreadmutexattrinit() function.
The protocol attribute defines the protocol to be followed
in utilizing mutexes. The value of protocol may be one of
PTHREADPRIONONE, PTHREADPRIOINHERIT, or
PTHREADPRIOPROTECT, which are defined by the header
.
When a thread owns a mutex with the PTHREADPRIONONE 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 PTHREADPRIOINHERIT
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
PTHREADPRIOPROTECT 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 pthreadmutexattrgetprotocol(3C)
While a thread is holding a mutex that has been initialized
with the PRIOINHERIT or PRIOPROTECT 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
schedsetparam(). Likewise, when a thread unlocks a mutex
that has been initialized with the PRIOINHERIT or
PRIOPROTECT 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 pthreadmutexlock() for a mutex
that was initialized with the protocol attribute
PTHREADPRIOINHERIT, 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
PTHREADPRIOINHERIT or PTHREADPRIOPROTECT protocol attri-
bute values should have its scheduling policy equal to
SCHEDFIFO or SCHEDR (see pthreadattrgetschedparam(3C)
and pthreadgetschedparam(3C)).
If a thread with scheduling policy equal to SCHEDOTHER uses
a mutex initialized with the PTHREADPRIOINHERIT or
PTHREADPRIOPROTECT protocol attribute value, the effect on
the thread's scheduling and priority is unspecified.
The POSIXTHREADPRIOINHERIT and
POSIXTHREADPRIOPROTECT 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 pthreadmutexattrgetprotocol(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
pthreadmutexattrgetprotocol() and
pthreadmutexattrsetprotocol() functions return 0. Other-
wise, an error number is returned to indicate the error.
ERORS
The pthreadmutexattrgetprotocol() and
pthreadmutexattrsetprotocol() functions will fail if:
EINVAL The value specified by attr is NUL.
ENOSYS Neither of the options POSIXTHREADPRIOPROTECT
and POSIXTHREADPRIOINHERIT is defined and the
system does not support the function.
ENOTSUP The value specified by protocol is an unsupported
value.
The pthreadmutexattrgetprotocol() and
pthreadmutexattrsetprotocol() 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.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 5 Feb 2008 3
Standard C Library Functions pthreadmutexattrgetprotocol(3C)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level MT-Safe
Standard See standards(5).
SEE ALSO
pthreadattrgetschedparam(3C), pthreadmutexinit(3C),
pthreadmutexattrinit(3C), schedsetparam(3C),
schedsetscheduler(3C), attributes(5), standards(5)
SunOS 5.11 Last change: 5 Feb 2008 4
|
