pthread_mutex_setprioceiling Subroutine



Purpose

Dynamically sets the value of the prioceiling attribute of a mutex.

Library

Threads Library (libpthreads.a)

Syntax

#include <pthread.h>

int pthread_mutex_setprioceiling (mutex, prioceiling, oldceiling)
pthread_mutex_t *mutex;
int prioceiling;
int *oldceiling;

Description

The pthread_mutex_setprioceiling subroutine dynamically sets the value
of the prioceiling attribute of the mutex mutex. This attribute specifies
the priority ceiling of the mutex, used in the priority protection
protocol to prevent priority inversions. It has no meaning if the
mutex uses another protocol. It first locks the mutex (waiting if
the mutex is already locked), then changes the value of the prioceiling
attribute, and finally unlocks the mutex.

Note:	The pthread.h header file must be the first included file of
each source file using the threads library.

Parameters

mutex	Specifies the target mutex.

prioceiling	Specifies the priority ceiling to set. It must be in the
range from 1 to 127, where 1 is the least favored priority, and 127
the most favored; it should be the priority of the highest priority
thread that can lock the mutex lock, or higher. Setting a lower value
may cause priority inversions.

oldceiling	Points to where the previous prioceiling attribute value
will be stored.

Return Values

Upon successful completion, the previous value of the prioceiling
attribute is returned via the oldceiling parameter, and 0 is returned.
Otherwise, an error code is returned.

Error Codes

The pthread_mutex_setprioceiling subroutine is unsuccessful if the
following is true:

EINVAL	The mutex parameter is not valid or the requested value for
prioceiling is not within the valid range.

ENOSYS	The priority protection POSIX option is not implemented.

EPERM	The calling thread does not have sufficient privilege to perform
the operation.

ESRCH	The mutex mutex does not exist.

Implementation Specifics

This subroutine is part of the Base Operating System (BOS) Runtime.

The implementation of this subroutine is dependent on the priority
protection POSIX option. The priority protection POSIX option is not
implemented in the current version of AIX.

Related Information

The pthread_mutex_getprioceiling subroutine, pthread_mutexattr_setprioceiling
subroutine.

Synchronization Scheduling.

Threads Library Options.

Threads Library Quick Reference.