147 lines
3.7 KiB
Plaintext
147 lines
3.7 KiB
Plaintext
'\"macro stdmacro
|
|
.TH pthread_mutexattr_setprotocol 3P
|
|
.SH NAME
|
|
pthread_mutexattr_setprotocol, pthread_mutexattr_getprotocol,
|
|
pthread_mutexattr_setprioceiling, pthread_mutexattr_getprioceiling \-
|
|
set/get a mutex attribute object's priority and protocol
|
|
.Op c p a
|
|
.SH C SYNOPSIS
|
|
.nf
|
|
.ft 3
|
|
#include <pthread.h>
|
|
.HP
|
|
.ft 3
|
|
int pthread_mutexattr_setprotocol(pthread_mutexattr_t \(**attr,
|
|
.br
|
|
int protocol);
|
|
.HP
|
|
.ft 3
|
|
int pthread_mutexattr_getprotocol(const pthread_mutexattr_t \(**attr,
|
|
.br
|
|
int \(**oprotocol);
|
|
.HP
|
|
.ft 3
|
|
int pthread_mutexattr_setprioceiling(pthread_mutexattr_t \(**attr,
|
|
.br
|
|
int prioceiling);
|
|
.HP
|
|
.ft 3
|
|
int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t \(**attr,
|
|
.br
|
|
int \(**oprioceiling);
|
|
.ft 1
|
|
.SH DESCRIPTION
|
|
These functions manipulate a mutex attribute object referenced by
|
|
.I attr
|
|
which has been previously created by
|
|
.IR pthread_mutexattr_init ().
|
|
.LP
|
|
The function
|
|
.IR pthread_mutexattr_setprotocol ()
|
|
defines the thread priority protocol to be followed when acquiring and
|
|
holding mutexes.
|
|
The
|
|
.I protocol
|
|
value may be one of
|
|
.BR PTHREAD_PRIO_NONE ,
|
|
.BR PTHREAD_PRIO_INHERIT ,
|
|
or
|
|
.BR PTHREAD_PRIO_PROTECT .
|
|
The function
|
|
.IR pthread_mutexattr_getprotocol ()
|
|
stores into the memory referenced by
|
|
.I oprotocol
|
|
the thread priority protocol associated with the named
|
|
mutex attribute object.
|
|
The default protocol is
|
|
.BR PTHREAD_PRIO_NONE .
|
|
.LP
|
|
When a thread owns a mutex with the
|
|
.B PTHREAD_PRIO_NONE
|
|
protocol attribute,
|
|
the thread's priority and scheduling are not affected by its mutex ownership.
|
|
.LP
|
|
When a thread owns one or more mutexes that have been initialized
|
|
with the
|
|
.B PTHREAD_PRIO_PROTECT
|
|
or
|
|
.B PTHREAD_PRIO_INHERIT
|
|
protocol, it will execute at the higher of its
|
|
current priority or the highest priority associated with any owned mutex.
|
|
.LP
|
|
For mutexes initialized with the
|
|
.B 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
|
|
.B PTHREAD_PRIO_INHERIT
|
|
protocol becomes blocked on another
|
|
mutex with the
|
|
.BR PTHREAD_PRIO_INHERIT ,
|
|
protocol, priority inheritance will be propagated
|
|
to the owning thread of this other mutex.)
|
|
.LP
|
|
For mutexes initialized with the
|
|
.B PTHREAD_PRIO_PROTECT
|
|
protocol, the priority associated with the mutex is set either by
|
|
calls to
|
|
.IR pthread_mutex_setprioceiling ()
|
|
or by call to
|
|
.IR pthread_mutexattr_setprioceiling ()
|
|
on the mutex attribute object that was used to initialized the mutex.
|
|
For
|
|
.IR pthread_mutexattr_setprioceiling (),
|
|
the values of
|
|
.I prioceiling
|
|
must be within the values returned by
|
|
.IR sched_get_priority_min ()
|
|
and
|
|
.IR sched_get_priority_max ()
|
|
for the
|
|
.B SCHED_FIFO
|
|
policy.
|
|
The function
|
|
.IR pthread_mutexattr_getprioceiling ()
|
|
stores into the memory referenced by
|
|
.I oprioceiling
|
|
the priority associated with the named mutex attribute object;
|
|
the default priority is
|
|
the return value from
|
|
.IR sched_get_priority_min ().
|
|
Note that a call to
|
|
.IR pthread_mutex_lock ()
|
|
will fail if the mutex protocol attribute is
|
|
.B PTHREAD_PRIO_PROTECT
|
|
and the priority associated with the mutex is less than the
|
|
calling thread's priority.
|
|
.PP
|
|
Priority inheritance is not supported for
|
|
.I process-shared
|
|
mutexes; all other protocols are supported, including priority ceiling.
|
|
.SH "DIAGNOSTICS"
|
|
All of the mutex attribute protocol functions return zero on success;
|
|
otherwise, an error number is returned:
|
|
.TP 15
|
|
.B [EINVAL]
|
|
The value specified by
|
|
.I protocol
|
|
or
|
|
.I prioceiling
|
|
is invalid.
|
|
.TP 15
|
|
.B [EINVAL]
|
|
The value specified by
|
|
.I protocol
|
|
is
|
|
.B PTHREAD_PRIO_INHERIT
|
|
and the
|
|
.I process-shared
|
|
attribute is set to
|
|
.BR PTHREAD_PROCESS_SHARED .
|
|
.SH "SEE ALSO"
|
|
pthread_mutex_lock(3P),
|
|
pthread_mutex_setprioceiling(3P),
|
|
pthread_mutexattr_init(3P),
|
|
sched_get_priority_min(3C),
|
|
sched_get_priority_max(3C).
|