Sun Microsystems, Inc.
spacerspacer
spacer www.sun.com docs.sun.com |
spacer
black dot
 
 
4.  Programming with Synchronization Objects Mutual Exclusion Lock Attributes Set Mutex Attribute's Priority Ceiling pthread_mutexattr_setprioceiling(3THR)  Previous   Contents   Next 
   
 

Return Values

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

If any of the following conditions occurs, pthread_mutexattr_setprioceiling() fails and returns the corresponding value.

 

ENOSYS

The option _POSIX_THREAD_PRIO_PROTECT is not defined and the implementation does not support the function.

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

 

EINVAL

The value specified by attr or prioceiling is invalid.

 

EPERM

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

Get Mutex Attribute's Priority Ceiling

pthread_mutexattr_getprioceiling(3THR)

pthread_mutexattr_getprioceiling(3THR) gets the priority ceiling attribute of a mutex attribute object.

#include <pthread.h>

int pthread_mutexattr_getprioceiling(const pthread_mutexatt_t *attr, 
												int *prioceiling);

attr designates the attribute object created by an earlier call to pthread_mutexattr_init().


Note - The attr mutex attribute object includes the priority ceiling attribute only if the symbol _POSIX_THREAD_PRIO_PROTECT is defined.


pthread_mutexattr_getprioceiling() returns the priority ceiling of initialized mutexes in prioceiling. The ceiling defines the minimum priority level at which the critical section guarded by the mutex is executed. prioceiling will be within the maximum range of priorities defined by SCHED_FIFO. To avoid priority inversion, prioceiling will be set to a priority higher than or equal to the highest priority of all the threads that might lock the particular mutex.

Return Values

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

If any of the following conditions occurs, pthread_mutexattr_getprioceiling() fails and returns the corresponding value.

 

ENOSYS

The option _POSIX_THREAD_PRIO_PROTECT is not defined and the implementation does not support the function.

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

 

EINVAL

The value specified by attr is invalid.

 

EPERM

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

Set Mutex's Priority Ceiling

pthread_mutex_setprioceiling(3THR)

pthread_mutex_setprioceiling(3THR) sets the priority ceiling of a mutex.

#include <pthread.h>

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

pthread_mutex_setprioceiling() changes the priority ceiling, prioceiling, of a mutex, mutex. pthread_mutex_setprioceiling() locks the mutex if it is unlocked, or blocks until it can successfully lock the mutex, changes the priority ceiling of the mutex and releases the mutex. The process of locking the mutex need not adhere to the priority protect protocol.

If pthread_mutex_setprioceiling() succeeds, the previous value of the priority ceiling is returned in old_ceiling. If pthread_mutex_setprioceiling() fails, the mutex priority ceiling remains unchanged.

Return Values

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

If the following condition occurs, pthread_mutexatt_setprioceiling() fails and returns the corresponding value.

 

ENOSYS

The option _POSIX_THREAD_PRIO_PROTECT is not defined and the implementation does not support the function.

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

 

EINVAL

The priority requested by prioceiling is out of range.

 

EINVAL

The value specified by mutex does not refer to a currently existing mutex.

 

ENOSYS

The implementation does not support the priority ceiling protocol for mutexes.

 

EPERM

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

Get Mutex's Priority Ceiling

pthread_mutex_getprioceiling(3THR)

pthread_mutex_getprioceiling(3THR) gets the priority ceiling of a mutex.

#include <pthread.h>

int pthread_mutex_getprioceiling(const pthread_mutex_t *mutex, 
											int *prioceiling);

pthread_mutex_getprioceiling() returns the priority ceiling, prioceiling of a mutex mutex.

Return Values

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

If any of the following conditions occurs, pthread_mutexatt_getprioceiling() fails and returns the corresponding value.

 

ENOSYS

The option _POSIX_THREAD_PRIO_PROTECT is not defined and the implementation does not support the function.

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

 

EINVAL

The value specified by mutex does not refer to a currently existing mutex.

 

ENOSYS

The implementation does not support the priority ceiling protocol for mutexes.

 

EPERM

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

Set Mutex's Robust Attribute

pthread_mutexattr_setrobust_np(3THR)

pthread_mutexattr_setrobust_np(3THR) sets the robust attribute of a mutex attribute object.

#include <pthread.h>

int pthread_mutexattr_setrobust_np(pthread_mutexattr_t *attr, 
												int *robustness);

Note - pthread_mutexattr_setrobust_np() applies only if the symbol _POSIX_THREAD_PRIO_INHERIT is defined.


attr points to the mutex attribute object previously created by a call to pthread_mutexattr_init().

robustness defines the behavior when the owner of the mutex dies. The value of robustness, defined in pthread.h, is PTHREAD_MUTEX_ROBUST_NP or PTHREAD_MUTEX_STALLED_NP. The default value is PTHREAD_MUTEX_STALLED_NP.

  • PTHREAD_MUTEX_ROBUST_NP

    When the owner of the mutex dies, all subsequent calls to pthread_mutex_lock() are blocked from progress in an unspecified manner.

  • PTHREAD_MUTEX_STALLED_NP

    When the owner of the mutex dies, the mutex is unlocked. The next owner of this mutex acquires it with an error return of EOWNWERDEAD.


    Note - Your application must check the return code from pthread_mutex_lock() for a mutex of this type.


    • The new owner of this mutex should make the state protected by the mutex consistent; this state might have been left inconsistent when the previous owner died.

    • If the new owner is able to make the state consistent, call pthread_mutex_consistent_np() for the mutex, and unlock the mutex.

    • If the new owner is not able to make the state consistent, do not call pthread_mutex_consistent_np() for the mutex, but unlock the mutex.

      All waiters are woken up and all subsequent calls to pthread_mutex_lock() fail to acquire the mutex. The return code is ENOTRECOVERABLE. The mutex can be made consistent by calling pthread_mutex_destroy() to uninitialize the mutex, and calling pthread_mutex_int() to reinitialize it.

    If the thread that acquire the lock with EOWNERDEAD died, the next owner acquires the lock with an EOWNERDEAD return code.

 
 
 
  Previous   Contents   Next