diff options
Diffstat (limited to 'posix_users/mutex.rst')
| -rw-r--r-- | posix_users/mutex.rst | 673 |
1 files changed, 0 insertions, 673 deletions
diff --git a/posix_users/mutex.rst b/posix_users/mutex.rst deleted file mode 100644 index 6fad624..0000000 --- a/posix_users/mutex.rst +++ /dev/null @@ -1,673 +0,0 @@ -.. 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:** |