PTHREAD_MUTEX(3) manual page

From 41f88a82b33cdb357c83b582381232733ed2d039 Mon Sep 17 00:00:00 2001 From: rpj Date: Thu, 5 May 2005 14:18:27 +0000 Subject: '' --- manual/pthread_mutex_init.html | 275 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 275 insertions(+) create mode 100644 manual/pthread_mutex_init.html (limited to 'manual/pthread_mutex_init.html') diff --git a/manual/pthread_mutex_init.html b/manual/pthread_mutex_init.html new file mode 100644 index 0000000..a56f77d --- /dev/null +++ b/manual/pthread_mutex_init.html @@ -0,0 +1,275 @@ + + + + + PTHREAD_MUTEX(3) manual page + + + + + + + +

Table of Contents

Name

pthread_mutex_init, pthread_mutex_lock, pthread_mutex_trylock, +pthread_mutex_timedlock, pthread_mutex_unlock, pthread_mutex_destroy +- operations on mutexes +

Synopsis

#include <pthread.h> +

#include <time.h>

pthread_mutex_t fastmutex = +PTHREAD_MUTEX_INITIALIZER; +

pthread_mutex_t recmutex = +PTHREAD_RECURSIVE_MUTEX_INITIALIZER; +

pthread_mutex_t errchkmutex = +PTHREAD_ERRORCHECK_MUTEX_INITIALIZER; +

pthread_mutex_t recmutex = +PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP; +

pthread_mutex_t errchkmutex = +PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP; +

int pthread_mutex_init(pthread_mutex_t *mutex, +const pthread_mutexattr_t *mutexattr); +

int pthread_mutex_lock(pthread_mutex_t *mutex); +

int pthread_mutex_trylock(pthread_mutex_t *mutex); +

int pthread_mutex_timedlock(pthread_mutex_t *mutex, +const struct timespec *abs_timeout); +

int pthread_mutex_unlock(pthread_mutex_t *mutex); +

int pthread_mutex_destroy(pthread_mutex_t *mutex); +

Description

A mutex is a MUTual EXclusion device, and is useful for protecting +shared data structures from concurrent modifications, and +implementing critical sections and monitors. +

A mutex has two possible states: unlocked (not owned by any +thread), and locked (owned by one thread). A mutex can never be owned +by two different threads simultaneously. A thread attempting to lock +a mutex that is already locked by another thread is suspended until +the owning thread unlocks the mutex first. +

pthread_mutex_init initializes the mutex object pointed to +by mutex according to the mutex attributes specified in +mutexattr. If mutexattr is NULL, default +attributes are used instead. +

The type of a mutex determines whether it can be locked again by a +thread that already owns it. The default type is “normal”. See +pthread_mutexattr_init(3) +for more information on mutex attributes. +

Variables of type pthread_mutex_t can also be initialized +statically, using the constants PTHREAD_MUTEX_INITIALIZER (for +normal “fast” mutexes), PTHREAD_RECURSIVE_MUTEX_INITIALIZER +(for recursive mutexes), and PTHREAD_ERRORCHECK_MUTEX_INITIALIZER +(for error checking mutexes). In +the Pthreads-w32 implementation, an application should still +call pthread_mutex_destroy at some point to ensure that any +resources consumed by the mutex are released.

pthread_mutex_lock locks the given mutex. If the mutex is +currently unlocked, it becomes locked and owned by the calling +thread, and pthread_mutex_lock returns immediately. If the +mutex is already locked by another thread, pthread_mutex_lock +suspends the calling thread until the mutex is unlocked. +

If the mutex is already locked by the calling thread, the behavior +of pthread_mutex_lock depends on the type of the mutex. If the +mutex is of the “normal” type, the calling thread is suspended +until the mutex is unlocked, thus effectively causing the calling +thread to deadlock. If the mutex is of the ‘‘error checking’’ +type, pthread_mutex_lock returns immediately with the error +code EDEADLK. If the mutex is of the ‘‘recursive’’ +type, pthread_mutex_lock succeeds and returns immediately, +recording the number of times the calling thread has locked the +mutex. An equal number of pthread_mutex_unlock operations must +be performed before the mutex returns to the unlocked state. +

pthread_mutex_trylock behaves identically to +pthread_mutex_lock, except that it does not block the calling +thread if the mutex is already locked by another thread (or by the +calling thread in the case of a “normal” mutex). Instead, +pthread_mutex_trylock returns immediately with the error code +EBUSY. +

pthread_mutex_timedlock behaves identically to +pthread_mutex_lock, except that if it cannot acquire the lock +before the abs_timeout time, the call returns with the error +code ETIMEDOUT. If the mutex can be locked immediately it is, +and the abs_timeout parameter is ignored.

pthread_mutex_unlock unlocks the given mutex. The mutex is +assumed to be locked and owned by the calling thread on entrance to +pthread_mutex_unlock. If the mutex is of the “normal” +type, pthread_mutex_unlock always returns it to the unlocked +state. If it is of the ‘‘recursive’’ type, it decrements the +locking count of the mutex (number of pthread_mutex_lock +operations performed on it by the calling thread), and only when this +count reaches zero is the mutex actually unlocked. +

On ‘‘error checking’’ mutexes, pthread_mutex_unlock +actually checks at run-time that the mutex is locked on entrance, and +that it was locked by the same thread that is now calling +pthread_mutex_unlock. If these conditions are not met, an +error code is returned and the mutex remains unchanged. ‘‘Normal’’ +mutexes perform no such checks, thus allowing a locked mutex to be +unlocked by a thread other than its owner. This is non-portable +behavior and is not meant to be used as a feature.

pthread_mutex_destroy destroys a mutex object, freeing the +resources it might hold. The mutex must be unlocked on entrance.

Cancellation

None of the mutex functions is a cancellation point, not even +pthread_mutex_lock, in spite of the fact that it can suspend a +thread for arbitrary durations. This way, the status of mutexes at +cancellation points is predictable, allowing cancellation handlers to +unlock precisely those mutexes that need to be unlocked before the +thread stops executing. Consequently, threads using deferred +cancellation should never hold a mutex for extended periods of time. +

Async-signal Safety

The mutex functions are not async-signal safe. What this means is +that they should not be called from a signal handler. In particular, +calling pthread_mutex_lock or pthread_mutex_unlock from +a signal handler may deadlock the calling thread. +

Return Value

pthread_mutex_init always returns 0. The other mutex +functions return 0 on success and a non-zero error code on error. +

Errors

The pthread_mutex_lock function returns the following error +code on error: +

EINVAL +: + the mutex has not been properly initialized. +
+ EDEADLK +: + the mutex is already locked by the calling thread (‘‘error + checking’’ mutexes only). +

+ +

+The pthread_mutex_trylock function returns the following error +codes on error: +

EBUSY +: + the mutex could not be acquired because it was currently locked. +
+ EINVAL +: + the mutex has not been properly initialized. +

+ +

+The pthread_mutex_timedlock function returns the following +error codes on error: +

ETIMEDOUT +: + the mutex could not be acquired before the abs_timeout time + arrived. +
+ EINVAL +: + the mutex has not been properly initialized. +

+ +

+The pthread_mutex_unlock function returns the following error +code on error: +

EINVAL +: + the mutex has not been properly initialized. +
+ EPERM +: + the calling thread does not own the mutex (‘‘error checking’’ + mutexes only). +

+ +

+The pthread_mutex_destroy function returns the following error +code on error: +

EBUSY +: + the mutex is currently locked. +

+ +

+Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32.

Example

A shared global variable x can be protected by a mutex as +follows: +

int x;
+pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;

+All accesses and modifications to x should be bracketed by +calls to pthread_mutex_lock and pthread_mutex_unlock as +follows: +

pthread_mutex_lock(&mut);
+/* operate on x */
+pthread_mutex_unlock(&mut);

Table of +Contents

Name +
+
Synopsis +
+
Description +
+
Cancellation +
+
Async-signal + Safety +
+
Return + Value +
+
Errors +
+
Author +
+
See + Also +
+
Example +
+

+ + -- cgit v1.2.3