mirror of
https://git.rtems.org/rtems-docs/
synced 2025-05-31 09:11:23 +08:00
627 lines
13 KiB
ReStructuredText
627 lines
13 KiB
ReStructuredText
Mutex Manager
|
||
#############
|
||
|
||
Introduction
|
||
============
|
||
|
||
The mutex manager implements the functionality required of the mutex
|
||
manager as defined by POSIX 1003.1b-1996. This standard requires that
|
||
a compliant operating system provide the facilties to ensure that
|
||
threads can operate with mutual exclusion from one another and
|
||
defines the API that must be provided.
|
||
|
||
The services provided by the mutex manager are:
|
||
|
||
- ``pthread_mutexattr_init`` - Initialize a Mutex Attribute Set
|
||
|
||
- ``pthread_mutexattr_destroy`` - Destroy a Mutex Attribute Set
|
||
|
||
- ``pthread_mutexattr_setprotocol`` - Set the Blocking Protocol
|
||
|
||
- ``pthread_mutexattr_getprotocol`` - Get the Blocking Protocol
|
||
|
||
- ``pthread_mutexattr_setprioceiling`` - Set the Priority Ceiling
|
||
|
||
- ``pthread_mutexattr_getprioceiling`` - Get the Priority Ceiling
|
||
|
||
- ``pthread_mutexattr_setpshared`` - Set the Visibility
|
||
|
||
- ``pthread_mutexattr_getpshared`` - Get the Visibility
|
||
|
||
- ``pthread_mutex_init`` - Initialize a Mutex
|
||
|
||
- ``pthread_mutex_destroy`` - Destroy a Mutex
|
||
|
||
- ``pthread_mutex_lock`` - Lock a Mutex
|
||
|
||
- ``pthread_mutex_trylock`` - Poll to Lock a Mutex
|
||
|
||
- ``pthread_mutex_timedlock`` - Lock a Mutex with Timeout
|
||
|
||
- ``pthread_mutex_unlock`` - Unlock a Mutex
|
||
|
||
- ``pthread_mutex_setprioceiling`` - Dynamically Set the Priority Ceiling
|
||
|
||
- ``pthread_mutex_getprioceiling`` - Dynamically Get the Priority Ceiling
|
||
|
||
Background
|
||
==========
|
||
|
||
Mutex Attributes
|
||
----------------
|
||
|
||
Mutex attributes are utilized only at mutex creation time. A mutex
|
||
attribute structure may be initialized and passed as an argument to
|
||
the ``mutex_init`` routine. Note that the priority ceiling of
|
||
a mutex may be set at run-time.
|
||
|
||
*blocking protcol*
|
||
is the XXX
|
||
|
||
*priority ceiling*
|
||
is the XXX
|
||
|
||
*pshared*
|
||
is the XXX
|
||
|
||
PTHREAD_MUTEX_INITIALIZER
|
||
-------------------------
|
||
|
||
This is a special value that a variable of type ``pthread_mutex_t``
|
||
may be statically initialized to as shown below:
|
||
.. code:: c
|
||
|
||
pthread_mutex_t my_mutex = PTHREAD_MUTEX_INITIALIZER;
|
||
|
||
This indicates that ``my_mutex`` will be automatically initialized
|
||
by an implicit call to ``pthread_mutex_init`` the first time
|
||
the mutex is used.
|
||
|
||
Note that the mutex will be initialized with default attributes.
|
||
|
||
Operations
|
||
==========
|
||
|
||
There is currently no text in this section.
|
||
|
||
Services
|
||
========
|
||
|
||
This section details the mutex manager’s services.
|
||
A subsection is dedicated to each of this manager’s services
|
||
and describes the calling sequence, related constants, usage,
|
||
and status codes.
|
||
|
||
pthread_mutexattr_init - Initialize a Mutex Attribute Set
|
||
---------------------------------------------------------
|
||
.. index:: pthread_mutexattr_init
|
||
.. index:: initialize a mutex attribute set
|
||
|
||
**CALLING SEQUENCE:**
|
||
|
||
.. code:: c
|
||
|
||
#include <pthread.h>
|
||
int pthread_mutexattr_init(
|
||
pthread_mutexattr_t \*attr
|
||
);
|
||
|
||
**STATUS CODES:**
|
||
|
||
*EINVAL*
|
||
The attribute pointer argument is invalid.
|
||
|
||
**DESCRIPTION:**
|
||
|
||
The ``pthread_mutexattr_init`` routine initializes the mutex attributes
|
||
object specified by ``attr`` with the default value for all of the
|
||
individual attributes.
|
||
|
||
**NOTES:**
|
||
|
||
XXX insert list of default attributes here.
|
||
|
||
pthread_mutexattr_destroy - Destroy a Mutex Attribute Set
|
||
---------------------------------------------------------
|
||
.. index:: pthread_mutexattr_destroy
|
||
.. index:: destroy a mutex attribute set
|
||
|
||
**CALLING SEQUENCE:**
|
||
|
||
.. code:: c
|
||
|
||
#include <pthread.h>
|
||
int pthread_mutexattr_destroy(
|
||
pthread_mutexattr_t \*attr
|
||
);
|
||
|
||
**STATUS CODES:**
|
||
|
||
*EINVAL*
|
||
The attribute pointer argument is invalid.
|
||
|
||
*EINVAL*
|
||
The attribute set is not initialized.
|
||
|
||
**DESCRIPTION:**
|
||
|
||
The ``pthread_mutex_attr_destroy`` routine is used to destroy a mutex
|
||
attributes object. The behavior of using an attributes object after
|
||
it is destroyed is implementation dependent.
|
||
|
||
**NOTES:**
|
||
|
||
NONE
|
||
|
||
pthread_mutexattr_setprotocol - Set the Blocking Protocol
|
||
---------------------------------------------------------
|
||
.. index:: pthread_mutexattr_setprotocol
|
||
.. index:: set the blocking protocol
|
||
|
||
**CALLING SEQUENCE:**
|
||
|
||
.. code:: c
|
||
|
||
#include <pthread.h>
|
||
int pthread_mutexattr_setprotocol(
|
||
pthread_mutexattr_t \*attr,
|
||
int protocol
|
||
);
|
||
|
||
**STATUS CODES:**
|
||
|
||
*EINVAL*
|
||
The attribute pointer argument is invalid.
|
||
|
||
*EINVAL*
|
||
The attribute set is not initialized.
|
||
|
||
*EINVAL*
|
||
The protocol argument is invalid.
|
||
|
||
**DESCRIPTION:**
|
||
|
||
The ``pthread_mutexattr_setprotocol`` routine is used to set value of the``protocol`` attribute. This attribute controls the order in which
|
||
threads waiting on this mutex will receive it.
|
||
|
||
The ``protocol`` can be one of the following:
|
||
|
||
*``PTHREAD_PRIO_NONE``*
|
||
in which case blocking order is FIFO.
|
||
|
||
*``PTHREAD_PRIO_INHERIT``*
|
||
in which case blocking order is priority with the priority inheritance
|
||
protocol in effect.
|
||
|
||
*``PTHREAD_PRIO_PROTECT``*
|
||
in which case blocking order is priority with the priority ceiling
|
||
protocol in effect.
|
||
|
||
**NOTES:**
|
||
|
||
There is currently no way to get simple priority blocking ordering
|
||
with POSIX mutexes even though this could easily by supported by RTEMS.
|
||
|
||
pthread_mutexattr_getprotocol - Get the Blocking Protocol
|
||
---------------------------------------------------------
|
||
.. index:: pthread_mutexattr_getprotocol
|
||
.. index:: get the blocking protocol
|
||
|
||
**CALLING SEQUENCE:**
|
||
|
||
.. code:: c
|
||
|
||
#include <pthread.h>
|
||
int pthread_mutexattr_getprotocol(
|
||
pthread_mutexattr_t \*attr,
|
||
int \*protocol
|
||
);
|
||
|
||
**STATUS CODES:**
|
||
|
||
*EINVAL*
|
||
The attribute pointer argument is invalid.
|
||
|
||
*EINVAL*
|
||
The attribute set is not initialized.
|
||
|
||
*EINVAL*
|
||
The protocol pointer argument is invalid.
|
||
|
||
**DESCRIPTION:**
|
||
|
||
The ``pthread_mutexattr_getprotocol`` routine is used to obtain
|
||
the value of the ``protocol`` attribute. This attribute controls
|
||
the order in which threads waiting on this mutex will receive it.
|
||
|
||
**NOTES:**
|
||
|
||
NONE
|
||
|
||
pthread_mutexattr_setprioceiling - Set the Priority Ceiling
|
||
-----------------------------------------------------------
|
||
.. index:: pthread_mutexattr_setprioceiling
|
||
.. index:: set the priority ceiling
|
||
|
||
**CALLING SEQUENCE:**
|
||
|
||
.. code:: c
|
||
|
||
#include <pthread.h>
|
||
int pthread_mutexattr_setprioceiling(
|
||
pthread_mutexattr_t \*attr,
|
||
int prioceiling
|
||
);
|
||
|
||
**STATUS CODES:**
|
||
|
||
*EINVAL*
|
||
The attribute pointer argument is invalid.
|
||
|
||
*EINVAL*
|
||
The attribute set is not initialized.
|
||
|
||
*EINVAL*
|
||
The prioceiling argument is invalid.
|
||
|
||
**DESCRIPTION:**
|
||
|
||
The ``pthread_mutexattr_setprioceiling`` routine is used to set value of the``prioceiling`` attribute. This attribute specifies the priority that
|
||
is the ceiling for threads obtaining this mutex. Any task obtaining this
|
||
mutex may not be of greater priority that the ceiling. If it is of lower
|
||
priority, then its priority will be elevated to ``prioceiling``.
|
||
|
||
**NOTES:**
|
||
|
||
NONE
|
||
|
||
pthread_mutexattr_getprioceiling - Get the Priority Ceiling
|
||
-----------------------------------------------------------
|
||
.. index:: pthread_mutexattr_getprioceiling
|
||
.. index:: get the priority ceiling
|
||
|
||
**CALLING SEQUENCE:**
|
||
|
||
.. code:: c
|
||
|
||
#include <pthread.h>
|
||
int pthread_mutexattr_getprioceiling(
|
||
const pthread_mutexattr_t \*attr,
|
||
int \*prioceiling
|
||
);
|
||
|
||
**STATUS CODES:**
|
||
|
||
*EINVAL*
|
||
The attribute pointer argument is invalid.
|
||
|
||
*EINVAL*
|
||
The attribute set is not initialized.
|
||
|
||
*EINVAL*
|
||
The prioceiling pointer argument is invalid.
|
||
|
||
**DESCRIPTION:**
|
||
|
||
The ``pthread_mutexattr_getprioceiling`` routine is used to obtain the
|
||
value of the ``prioceiling`` attribute. This attribute specifies the
|
||
priority ceiling for this mutex.
|
||
|
||
**NOTES:**
|
||
|
||
NONE
|
||
|
||
pthread_mutexattr_setpshared - Set the Visibility
|
||
-------------------------------------------------
|
||
.. index:: pthread_mutexattr_setpshared
|
||
.. index:: set the visibility
|
||
|
||
**CALLING SEQUENCE:**
|
||
|
||
.. code:: c
|
||
|
||
#include <pthread.h>
|
||
int pthread_mutexattr_setpshared(
|
||
pthread_mutexattr_t \*attr,
|
||
int pshared
|
||
);
|
||
|
||
**STATUS CODES:**
|
||
|
||
*EINVAL*
|
||
The attribute pointer argument is invalid.
|
||
|
||
*EINVAL*
|
||
The attribute set is not initialized.
|
||
|
||
*EINVAL*
|
||
The pshared argument is invalid.
|
||
|
||
**DESCRIPTION:**
|
||
|
||
**NOTES:**
|
||
|
||
pthread_mutexattr_getpshared - Get the Visibility
|
||
-------------------------------------------------
|
||
.. index:: pthread_mutexattr_getpshared
|
||
.. index:: get the visibility
|
||
|
||
**CALLING SEQUENCE:**
|
||
|
||
.. code:: c
|
||
|
||
#include <pthread.h>
|
||
int pthread_mutexattr_getpshared(
|
||
const pthread_mutexattr_t \*attr,
|
||
int \*pshared
|
||
);
|
||
|
||
**STATUS CODES:**
|
||
|
||
*EINVAL*
|
||
The attribute pointer argument is invalid.
|
||
|
||
*EINVAL*
|
||
The attribute set is not initialized.
|
||
|
||
*EINVAL*
|
||
The pshared pointer argument is invalid.
|
||
|
||
**DESCRIPTION:**
|
||
|
||
**NOTES:**
|
||
|
||
pthread_mutex_init - Initialize a Mutex
|
||
---------------------------------------
|
||
.. index:: pthread_mutex_init
|
||
.. index:: initialize a mutex
|
||
|
||
**CALLING SEQUENCE:**
|
||
|
||
.. code:: c
|
||
|
||
#include <pthread.h>
|
||
int pthread_mutex_init(
|
||
pthread_mutex_t \*mutex,
|
||
const pthread_mutexattr_t \*attr
|
||
);
|
||
|
||
**STATUS CODES:**
|
||
|
||
*EINVAL*
|
||
The attribute set is not initialized.
|
||
|
||
*EINVAL*
|
||
The specified protocol is invalid.
|
||
|
||
*EAGAIN*
|
||
The system lacked the necessary resources to initialize another mutex.
|
||
|
||
*ENOMEM*
|
||
Insufficient memory exists to initialize the mutex.
|
||
|
||
*EBUSY*
|
||
Attempted to reinialize the object reference by mutex, a previously
|
||
initialized, but not yet destroyed.
|
||
|
||
**DESCRIPTION:**
|
||
|
||
**NOTES:**
|
||
|
||
pthread_mutex_destroy - Destroy a Mutex
|
||
---------------------------------------
|
||
.. index:: pthread_mutex_destroy
|
||
.. index:: destroy a mutex
|
||
|
||
**CALLING SEQUENCE:**
|
||
|
||
.. code:: c
|
||
|
||
#include <pthread.h>
|
||
int pthread_mutex_destroy(
|
||
pthread_mutex_t \*mutex
|
||
);
|
||
|
||
**STATUS CODES:**
|
||
|
||
*EINVAL*
|
||
The specified mutex is invalid.
|
||
|
||
*EBUSY*
|
||
Attempted to destroy the object reference by mutex, while it is locked or
|
||
referenced by another thread.
|
||
|
||
**DESCRIPTION:**
|
||
|
||
**NOTES:**
|
||
|
||
pthread_mutex_lock - Lock a Mutex
|
||
---------------------------------
|
||
.. index:: pthread_mutex_lock
|
||
.. index:: lock a mutex
|
||
|
||
**CALLING SEQUENCE:**
|
||
|
||
.. code:: c
|
||
|
||
#include <pthread.h>
|
||
int pthread_mutex_lock(
|
||
pthread_mutex_t \*mutex
|
||
);
|
||
|
||
**STATUS CODES:**
|
||
|
||
*EINVAL*
|
||
The specified mutex is invalid.
|
||
|
||
*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.
|
||
|
||
*EDEADLK*
|
||
The current thread already owns the mutex.
|
||
|
||
**DESCRIPTION:**
|
||
|
||
**NOTES:**
|
||
|
||
pthread_mutex_trylock - Poll to Lock a Mutex
|
||
--------------------------------------------
|
||
.. index:: pthread_mutex_trylock
|
||
.. index:: poll to lock a mutex
|
||
|
||
**CALLING SEQUENCE:**
|
||
|
||
.. code:: c
|
||
|
||
#include <pthread.h>
|
||
int pthread_mutex_trylock(
|
||
pthread_mutex_t \*mutex
|
||
);
|
||
|
||
**STATUS CODES:**
|
||
|
||
*EINVAL*
|
||
The specified mutex is invalid.
|
||
|
||
*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.
|
||
|
||
*EBUSY*
|
||
The mutex is already locked.
|
||
|
||
**DESCRIPTION:**
|
||
|
||
**NOTES:**
|
||
|
||
pthread_mutex_timedlock - Lock a Mutex with Timeout
|
||
---------------------------------------------------
|
||
.. index:: pthread_mutex_timedlock
|
||
.. index:: lock a mutex with timeout
|
||
|
||
**CALLING SEQUENCE:**
|
||
|
||
.. code:: c
|
||
|
||
#include <pthread.h>
|
||
#include <time.h>
|
||
int pthread_mutex_timedlock(
|
||
pthread_mutex_t \*mutex,
|
||
const struct timespec \*timeout
|
||
);
|
||
|
||
**STATUS CODES:**
|
||
|
||
*EINVAL*
|
||
The specified mutex is invalid.
|
||
|
||
*EINVAL*
|
||
The nanoseconds field of timeout is invalid.
|
||
|
||
*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.
|
||
|
||
*EDEADLK*
|
||
The current thread already owns the mutex.
|
||
|
||
*ETIMEDOUT*
|
||
The calling thread was unable to obtain the mutex within the specified
|
||
timeout period.
|
||
|
||
**DESCRIPTION:**
|
||
|
||
**NOTES:**
|
||
|
||
pthread_mutex_unlock - Unlock a Mutex
|
||
-------------------------------------
|
||
.. index:: pthread_mutex_unlock
|
||
.. index:: unlock a mutex
|
||
|
||
**CALLING SEQUENCE:**
|
||
|
||
.. code:: c
|
||
|
||
#include <pthread.h>
|
||
int pthread_mutex_unlock(
|
||
pthread_mutex_t \*mutex
|
||
);
|
||
|
||
**STATUS CODES:**
|
||
|
||
*EINVAL*
|
||
The specified mutex is invalid.
|
||
|
||
**DESCRIPTION:**
|
||
|
||
**NOTES:**
|
||
|
||
pthread_mutex_setprioceiling - Dynamically Set the Priority Ceiling
|
||
-------------------------------------------------------------------
|
||
.. index:: pthread_mutex_setprioceiling
|
||
.. index:: dynamically set the priority ceiling
|
||
|
||
**CALLING SEQUENCE:**
|
||
|
||
.. code:: c
|
||
|
||
#include <pthread.h>
|
||
int pthread_mutex_setprioceiling(
|
||
pthread_mutex_t \*mutex,
|
||
int prioceiling,
|
||
int \*oldceiling
|
||
);
|
||
|
||
**STATUS CODES:**
|
||
|
||
*EINVAL*
|
||
The oldceiling pointer parameter is invalid.
|
||
|
||
*EINVAL*
|
||
The prioceiling parameter is an invalid priority.
|
||
|
||
*EINVAL*
|
||
The specified mutex is invalid.
|
||
|
||
**DESCRIPTION:**
|
||
|
||
**NOTES:**
|
||
|
||
pthread_mutex_getprioceiling - Get the Current Priority Ceiling
|
||
---------------------------------------------------------------
|
||
.. index:: pthread_mutex_getprioceiling
|
||
.. index:: get the current priority ceiling
|
||
|
||
**CALLING SEQUENCE:**
|
||
|
||
.. code:: c
|
||
|
||
#include <pthread.h>
|
||
int pthread_mutex_getprioceiling(
|
||
pthread_mutex_t \*mutex,
|
||
int \*prioceiling
|
||
);
|
||
|
||
**STATUS CODES:**
|
||
|
||
*EINVAL*
|
||
The prioceiling pointer parameter is invalid.
|
||
|
||
*EINVAL*
|
||
The specified mutex is invalid.
|
||
|
||
**DESCRIPTION:**
|
||
|
||
**NOTES:**
|
||
|
||
.. COMMENT: COPYRIGHT (c) 1988-2002.
|
||
|
||
.. COMMENT: On-Line Applications Research Corporation (OAR).
|
||
|
||
.. COMMENT: All rights reserved.
|
||
|