forked from Imagelibrary/rtems
643 lines
12 KiB
Plaintext
643 lines
12 KiB
Plaintext
@c
|
|
@c COPYRIGHT (c) 1988-1998.
|
|
@c On-Line Applications Research Corporation (OAR).
|
|
@c All rights reserved.
|
|
@c
|
|
@c $Id$
|
|
@c
|
|
|
|
@ifinfo
|
|
@node Mutex Manager, Mutex Manager Introduction, alarm, Top
|
|
@end ifinfo
|
|
@chapter Mutex Manager
|
|
@ifinfo
|
|
@menu
|
|
* Mutex Manager Introduction::
|
|
* Mutex Manager Background::
|
|
* Mutex Manager Operations::
|
|
* Mutex Manager Directives::
|
|
@end menu
|
|
@end ifinfo
|
|
|
|
@ifinfo
|
|
@node Mutex Manager Introduction, Mutex Manager Background, Mutex Manager, Mutex Manager
|
|
@end ifinfo
|
|
@section Introduction
|
|
|
|
The mutex manager ...
|
|
|
|
The directives provided by the mutex manager are:
|
|
|
|
@itemize @bullet
|
|
@item @code{pthread_mutexattr_init} -
|
|
@item @code{pthread_mutexattr_destroy} -
|
|
@item @code{pthread_mutexattr_setprotocol} -
|
|
@item @code{pthread_mutexattr_getprotocol} -
|
|
@item @code{pthread_mutexattr_setprioceiling} -
|
|
@item @code{pthread_mutexattr_getprioceiling} -
|
|
@item @code{pthread_mutexattr_setpshared} -
|
|
@item @code{pthread_mutexattr_getpshared} -
|
|
@item @code{pthread_mutex_init} -
|
|
@item @code{pthread_mutex_destroy} -
|
|
@item @code{pthread_mutex_lock} -
|
|
@item @code{pthread_mutex_trylock} -
|
|
@item @code{pthread_mutex_timedlock} -
|
|
@item @code{pthread_mutex_unlock} -
|
|
@item @code{pthread_mutex_setprioceiling} -
|
|
@item @code{pthread_mutex_getprioceiling} -
|
|
@end itemize
|
|
|
|
@ifinfo
|
|
@node Mutex Manager Background, Mutex Manager Operations, Mutex Manager Introduction, Mutex Manager
|
|
@end ifinfo
|
|
@section Background
|
|
|
|
@ifinfo
|
|
@node Mutex Manager Operations, Mutex Manager Directives, Mutex Manager Background, Mutex Manager
|
|
@end ifinfo
|
|
@section Operations
|
|
|
|
@ifinfo
|
|
@node Mutex Manager Directives, pthread_mutexattr_init, Mutex Manager Operations, Mutex Manager
|
|
@end ifinfo
|
|
@section Directives
|
|
@ifinfo
|
|
@menu
|
|
* pthread_mutexattr_init::
|
|
* pthread_mutexattr_destroy::
|
|
* pthread_mutexattr_setprotocol::
|
|
* pthread_mutexattr_getprotocol::
|
|
* pthread_mutexattr_setprioceiling::
|
|
* pthread_mutexattr_getprioceiling::
|
|
* pthread_mutexattr_setpshared::
|
|
* pthread_mutexattr_getpshared::
|
|
* pthread_mutex_init::
|
|
* pthread_mutex_destroy::
|
|
* pthread_mutex_lock::
|
|
* pthread_mutex_trylock::
|
|
* pthread_mutex_timedlock::
|
|
* pthread_mutex_unlock::
|
|
* pthread_mutex_setprioceiling::
|
|
* pthread_mutex_getprioceiling::
|
|
@end menu
|
|
@end ifinfo
|
|
|
|
This section details the mutex manager's directives.
|
|
A subsection is dedicated to each of this manager's directives
|
|
and describes the calling sequence, related constants, usage,
|
|
and status codes.
|
|
|
|
@page
|
|
@ifinfo
|
|
@node pthread_mutexattr_init, pthread_mutexattr_destroy, Mutex Manager Directives, Mutex Manager Directives
|
|
@end ifinfo
|
|
@subsection pthread_mutexattr_init
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <pthread.h>
|
|
|
|
int pthread_mutexattr_init(
|
|
pthread_mutexattr_t *attr
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The attribute pointer argument is invalid.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
@page
|
|
@ifinfo
|
|
@node pthread_mutexattr_destroy, pthread_mutexattr_setprotocol, pthread_mutexattr_init, Mutex Manager Directives
|
|
@end ifinfo
|
|
@subsection pthread_mutexattr_destroy
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <pthread.h>
|
|
|
|
int pthread_mutexattr_destroy(
|
|
pthread_mutexattr_t *attr
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The attribute pointer argument is invalid.
|
|
|
|
@item EINVAL
|
|
The attribute set is not initialized.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
@page
|
|
@ifinfo
|
|
@node pthread_mutexattr_setprotocol, pthread_mutexattr_getprotocol, pthread_mutexattr_destroy, Mutex Manager Directives
|
|
@end ifinfo
|
|
@subsection pthread_mutexattr_setprotocol
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <pthread.h>
|
|
|
|
int pthread_mutexattr_setprotocol(
|
|
pthread_mutexattr_t *attr,
|
|
int protocol
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The attribute pointer argument is invalid.
|
|
|
|
@item EINVAL
|
|
The attribute set is not initialized.
|
|
|
|
@item EINVAL
|
|
The protocol argument is invalid.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
@page
|
|
@ifinfo
|
|
@node pthread_mutexattr_getprotocol, pthread_mutexattr_setprioceiling, pthread_mutexattr_setprotocol, Mutex Manager Directives
|
|
@end ifinfo
|
|
@subsection pthread_mutexattr_getprotocol
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <pthread.h>
|
|
|
|
int pthread_mutexattr_getprotocol(
|
|
pthread_mutexattr_t *attr,
|
|
int *protocol
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The attribute pointer argument is invalid.
|
|
|
|
@item EINVAL
|
|
The attribute set is not initialized.
|
|
|
|
@item EINVAL
|
|
The protocol pointer argument is invalid.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
@page
|
|
@ifinfo
|
|
@node pthread_mutexattr_setprioceiling, pthread_mutexattr_getprioceiling, pthread_mutexattr_getprotocol, Mutex Manager Directives
|
|
@end ifinfo
|
|
@subsection pthread_mutexattr_setprioceiling
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <pthread.h>
|
|
|
|
int pthread_mutexattr_setprioceiling(
|
|
pthread_mutexattr_t *attr,
|
|
int prioceiling
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The attribute pointer argument is invalid.
|
|
|
|
@item EINVAL
|
|
The attribute set is not initialized.
|
|
|
|
@item EINVAL
|
|
The prioceiling argument is invalid.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
@page
|
|
@ifinfo
|
|
@node pthread_mutexattr_getprioceiling, pthread_mutexattr_setpshared, pthread_mutexattr_setprioceiling, Mutex Manager Directives
|
|
@end ifinfo
|
|
@subsection pthread_mutexattr_getprioceiling
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <pthread.h>
|
|
|
|
int pthread_mutexattr_getprioceiling(
|
|
const pthread_mutexattr_t *attr,
|
|
int *prioceiling
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The attribute pointer argument is invalid.
|
|
|
|
@item EINVAL
|
|
The attribute set is not initialized.
|
|
|
|
@item EINVAL
|
|
The prioceiling pointer argument is invalid.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
@page
|
|
@ifinfo
|
|
@node pthread_mutexattr_setpshared, pthread_mutexattr_getpshared, pthread_mutexattr_getprioceiling, Mutex Manager Directives
|
|
@end ifinfo
|
|
@subsection pthread_mutexattr_setpshared
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <pthread.h>
|
|
|
|
int pthread_mutexattr_setpshared(
|
|
pthread_mutexattr_t *attr,
|
|
int pshared
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The attribute pointer argument is invalid.
|
|
|
|
@item EINVAL
|
|
The attribute set is not initialized.
|
|
|
|
@item EINVAL
|
|
The pshared argument is invalid.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
@page
|
|
@ifinfo
|
|
@node pthread_mutexattr_getpshared, pthread_mutex_init, pthread_mutexattr_setpshared, Mutex Manager Directives
|
|
@end ifinfo
|
|
@subsection pthread_mutexattr_getpshared
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <pthread.h>
|
|
|
|
int pthread_mutexattr_getpshared(
|
|
const pthread_mutexattr_t *attr,
|
|
int *pshared
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The attribute pointer argument is invalid.
|
|
|
|
@item EINVAL
|
|
The attribute set is not initialized.
|
|
|
|
@item EINVAL
|
|
The pshared pointer argument is invalid.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
@page
|
|
@ifinfo
|
|
@node pthread_mutex_init, pthread_mutex_destroy, pthread_mutexattr_getpshared, Mutex Manager Directives
|
|
@end ifinfo
|
|
@subsection pthread_mutex_init
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <pthread.h>
|
|
|
|
int pthread_mutex_init(
|
|
pthread_mutex_t *mutex,
|
|
const pthread_mutexattr_t *attr
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The attribute set is not initialized.
|
|
|
|
@item EINVAL
|
|
The specified protocol is invalid.
|
|
|
|
@item EAGAIN
|
|
The system lacked the necessary resources to initialize another mutex.
|
|
|
|
@item ENOMEM
|
|
Insufficient memory exists to initialize the mutex.
|
|
|
|
@item EBUSY
|
|
Attempted to reinialize the object reference by mutex, a previously
|
|
initialized, but not yet destroyed.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
@page
|
|
@ifinfo
|
|
@node pthread_mutex_destroy, pthread_mutex_lock, pthread_mutex_init, Mutex Manager Directives
|
|
@end ifinfo
|
|
@subsection pthread_mutex_destroy
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <pthread.h>
|
|
|
|
int pthread_mutex_destroy(
|
|
pthread_mutex_t *mutex
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The specified mutex is invalid.
|
|
|
|
@item EBUSY
|
|
Attempted to destroy the object reference by mutex, while it is locked or
|
|
referenced by another thread.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
@page
|
|
@ifinfo
|
|
@node pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_destroy, Mutex Manager Directives
|
|
@end ifinfo
|
|
@subsection pthread_mutex_lock
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <pthread.h>
|
|
|
|
int pthread_mutex_lock(
|
|
pthread_mutex_t *mutex
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The specified mutex is invalid.
|
|
|
|
@item EINVAL
|
|
The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the
|
|
priority of the calling thread is higher than the current priority
|
|
ceiling.
|
|
|
|
@item EDEADLK
|
|
The current thread already owns the mutex.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
@page
|
|
@ifinfo
|
|
@node pthread_mutex_trylock, pthread_mutex_timedlock, pthread_mutex_lock, Mutex Manager Directives
|
|
@end ifinfo
|
|
@subsection pthread_mutex_trylock
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <pthread.h>
|
|
|
|
int pthread_mutex_trylock(
|
|
pthread_mutex_t *mutex
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The specified mutex is invalid.
|
|
|
|
@item EINVAL
|
|
The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the
|
|
priority of the calling thread is higher than the current priority
|
|
ceiling.
|
|
|
|
@item EDEADLK
|
|
The current thread already owns the mutex.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
@page
|
|
@ifinfo
|
|
@node pthread_mutex_timedlock, pthread_mutex_unlock, pthread_mutex_trylock, Mutex Manager Directives
|
|
@end ifinfo
|
|
@subsection pthread_mutex_timedlock
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <pthread.h>
|
|
#include <time.h>
|
|
|
|
int pthread_mutex_timedlock(
|
|
pthread_mutex_t *mutex,
|
|
const struct timespec *timeout
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The specified mutex is invalid.
|
|
|
|
@item EINVAL
|
|
The nanoseconds field of timeout is invalid.
|
|
|
|
@item EINVAL
|
|
The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the
|
|
priority of the calling thread is higher than the current priority
|
|
ceiling.
|
|
|
|
@item EDEADLK
|
|
The current thread already owns the mutex.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
|
|
@page
|
|
@ifinfo
|
|
@node pthread_mutex_unlock, pthread_mutex_setprioceiling, pthread_mutex_timedlock, Mutex Manager Directives
|
|
@end ifinfo
|
|
@subsection pthread_mutex_unlock
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <pthread.h>
|
|
|
|
int pthread_mutex_unlock(
|
|
pthread_mutex_t *mutex
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The specified mutex is invalid.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
@page
|
|
@ifinfo
|
|
@node pthread_mutex_setprioceiling, pthread_mutex_getprioceiling, pthread_mutex_unlock, Mutex Manager Directives
|
|
@end ifinfo
|
|
@subsection pthread_mutex_setprioceiling
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <pthread.h>
|
|
|
|
int pthread_mutex_setprioceiling(
|
|
pthread_mutex_t *mutex,
|
|
int prioceiling,
|
|
int *oldceiling
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The oldceiling pointer parameter is invalid.
|
|
|
|
@item EINVAL
|
|
The prioceiling parameter is an invalid priority.
|
|
|
|
@item EINVAL
|
|
The specified mutex is invalid.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|
|
@page
|
|
@ifinfo
|
|
@node pthread_mutex_getprioceiling, Condition Variable Manager, pthread_mutex_setprioceiling, Mutex Manager Directives
|
|
@end ifinfo
|
|
@subsection pthread_mutex_getprioceiling
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@example
|
|
#include <pthread.h>
|
|
|
|
int pthread_mutex_getprioceiling(
|
|
pthread_mutex_t *mutex,
|
|
int *prioceiling
|
|
);
|
|
@end example
|
|
|
|
@subheading STATUS CODES:
|
|
|
|
@table @b
|
|
@item EINVAL
|
|
The prioceiling pointer parameter is invalid.
|
|
|
|
@item EINVAL
|
|
The specified mutex is invalid.
|
|
|
|
@end table
|
|
|
|
@subheading DESCRIPTION:
|
|
|
|
@subheading NOTES:
|
|
|