summaryrefslogtreecommitdiffstats
path: root/posix-users/mutex.rst
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2016-11-03 16:58:08 +1100
committerChris Johns <chrisj@rtems.org>2016-11-03 16:58:08 +1100
commit72a62ad88f82fe1ffee50024db4dd0f3fa5806f7 (patch)
tree6b0e527e67141f8126ba56b8a3c1eb90aeed5849 /posix-users/mutex.rst
parentwaf: Use separate doctrees so avoid sphinx clashes. (diff)
downloadrtems-docs-72a62ad88f82fe1ffee50024db4dd0f3fa5806f7.tar.bz2
Rename all manuals with an _ to have a -. It helps released naming of files.
Diffstat (limited to 'posix-users/mutex.rst')
-rw-r--r--posix-users/mutex.rst673
1 files changed, 673 insertions, 0 deletions
diff --git a/posix-users/mutex.rst b/posix-users/mutex.rst
new file mode 100644
index 0000000..6fad624
--- /dev/null
+++ b/posix-users/mutex.rst
@@ -0,0 +1,673 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
+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.
+
+.. list-table::
+ :class: rtems-table
+
+ * - *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-block:: 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:
+
+pthread_mutexattr_init - Initialize a Mutex Attribute Set
+---------------------------------------------------------
+.. index:: pthread_mutexattr_init
+.. index:: initialize a mutex attribute set
+
+**CALLING SEQUENCE:**
+
+.. code-block:: 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:
+
+pthread_mutexattr_destroy - Destroy a Mutex Attribute Set
+---------------------------------------------------------
+.. index:: pthread_mutexattr_destroy
+.. index:: destroy a mutex attribute set
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_mutexattr_destroy(
+ pthread_mutexattr_t *attr
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``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:
+
+pthread_mutexattr_setprotocol - Set the Blocking Protocol
+---------------------------------------------------------
+.. index:: pthread_mutexattr_setprotocol
+.. index:: set the blocking protocol
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_mutexattr_setprotocol(
+ pthread_mutexattr_t *attr,
+ int protocol
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``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:
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``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:
+
+pthread_mutexattr_getprotocol - Get the Blocking Protocol
+---------------------------------------------------------
+.. index:: pthread_mutexattr_getprotocol
+.. index:: get the blocking protocol
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_mutexattr_getprotocol(
+ pthread_mutexattr_t *attr,
+ int *protocol
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``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:
+
+pthread_mutexattr_setprioceiling - Set the Priority Ceiling
+-----------------------------------------------------------
+.. index:: pthread_mutexattr_setprioceiling
+.. index:: set the priority ceiling
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_mutexattr_setprioceiling(
+ pthread_mutexattr_t *attr,
+ int prioceiling
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``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:
+
+pthread_mutexattr_getprioceiling - Get the Priority Ceiling
+-----------------------------------------------------------
+.. index:: pthread_mutexattr_getprioceiling
+.. index:: get the priority ceiling
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_mutexattr_getprioceiling(
+ const pthread_mutexattr_t *attr,
+ int *prioceiling
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``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:
+
+pthread_mutexattr_setpshared - Set the Visibility
+-------------------------------------------------
+.. index:: pthread_mutexattr_setpshared
+.. index:: set the visibility
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_mutexattr_setpshared(
+ pthread_mutexattr_t *attr,
+ int pshared
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``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:
+
+pthread_mutexattr_getpshared - Get the Visibility
+-------------------------------------------------
+.. index:: pthread_mutexattr_getpshared
+.. index:: get the visibility
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_mutexattr_getpshared(
+ const pthread_mutexattr_t *attr,
+ int *pshared
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``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:
+
+pthread_mutex_init - Initialize a Mutex
+---------------------------------------
+.. index:: pthread_mutex_init
+.. index:: initialize a mutex
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_mutex_init(
+ pthread_mutex_t *mutex,
+ const pthread_mutexattr_t *attr
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``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:
+
+pthread_mutex_destroy - Destroy a Mutex
+---------------------------------------
+.. index:: pthread_mutex_destroy
+.. index:: destroy a mutex
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_mutex_destroy(
+ pthread_mutex_t *mutex
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``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:
+
+pthread_mutex_lock - Lock a Mutex
+---------------------------------
+.. index:: pthread_mutex_lock
+.. index:: lock a mutex
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_mutex_lock(
+ pthread_mutex_t *mutex
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``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:
+
+pthread_mutex_trylock - Poll to Lock a Mutex
+--------------------------------------------
+.. index:: pthread_mutex_trylock
+.. index:: poll to lock a mutex
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_mutex_trylock(
+ pthread_mutex_t *mutex
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``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:
+
+pthread_mutex_timedlock - Lock a Mutex with Timeout
+---------------------------------------------------
+.. index:: pthread_mutex_timedlock
+.. index:: lock a mutex with timeout
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ #include <time.h>
+ int pthread_mutex_timedlock(
+ pthread_mutex_t *mutex,
+ const struct timespec *timeout
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``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:
+
+pthread_mutex_unlock - Unlock a Mutex
+-------------------------------------
+.. index:: pthread_mutex_unlock
+.. index:: unlock a mutex
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_mutex_unlock(
+ pthread_mutex_t *mutex
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The specified mutex is invalid.
+
+**DESCRIPTION:**
+
+**NOTES:**
+
+.. _pthread_mutex_setprioceiling:
+
+pthread_mutex_setprioceiling - Dynamically Set the Priority Ceiling
+-------------------------------------------------------------------
+.. index:: pthread_mutex_setprioceiling
+.. index:: dynamically set the priority ceiling
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_mutex_setprioceiling(
+ pthread_mutex_t *mutex,
+ int prioceiling,
+ int *oldceiling
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``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:
+
+pthread_mutex_getprioceiling - Get the Current Priority Ceiling
+---------------------------------------------------------------
+.. index:: pthread_mutex_getprioceiling
+.. index:: get the current priority ceiling
+
+**CALLING SEQUENCE:**
+
+.. code-block:: c
+
+ #include <pthread.h>
+ int pthread_mutex_getprioceiling(
+ pthread_mutex_t *mutex,
+ int *prioceiling
+ );
+
+**STATUS CODES:**
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``EINVAL``
+ - The prioceiling pointer parameter is invalid.
+ * - ``EINVAL``
+ - The specified mutex is invalid.
+
+**DESCRIPTION:**
+
+**NOTES:**