PTHREAD_MUTEX(3) manual page

From 2fe8aba6a8a4ce09f353f34881c77f93a9c01ca3 Mon Sep 17 00:00:00 2001 From: rpj Date: Fri, 6 May 2011 02:11:50 +0000 Subject: Robust mutexes merged from devel branch --- manual/pthread_mutex_init.html | 225 ++++++++++++++++++++++++++++------------- 1 file changed, 152 insertions(+), 73 deletions(-) (limited to 'manual/pthread_mutex_init.html') diff --git a/manual/pthread_mutex_init.html b/manual/pthread_mutex_init.html index f9982cf..cdb333e 100644 --- a/manual/pthread_mutex_init.html +++ b/manual/pthread_mutex_init.html @@ -3,22 +3,37 @@ PTHREAD_MUTEX(3) manual page - + - + + + + + -

POSIX Threads for Windows – REFERENCE - Pthreads-w32

POSIX Threads for Windows – REFERENCE - +Pthreads-w32

Reference Index

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 +pthread_mutex_timedlock, pthread_mutex_unlock, +pthread_mutex_consistent, pthread_mutex_destroy - operations on +mutexes

Synopsis

#include <pthread.h>

#include <time.h>

@@ -49,9 +64,11 @@ const pthread_mutexattr_t *mutexattr);

int pthread_mutex_unlock(pthread_mutex_t *mutex);

int pthread_mutex_consistent(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. @@ -76,16 +93,22 @@ for more information on mutex attributes. 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 +(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.

Any mutex type can be +initialized as a robust mutex. +See pthread_mutexattr_init(3) +for more information as well as the +section Robust Mutexes +below.

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. -

+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 @@ -101,15 +124,18 @@ 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. +calling thread in the case of a “normal” or “errorcheck” +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_consistent may only be called for +PTHREAD_MUTEX_ROBUST mutexes. It simply marks the mutex as +consistent. See Robust Mutexes below.

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” @@ -117,19 +143,53 @@ 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. -

+count reaches zero is the mutex actually unlocked. In Pthreads-win32, +non-robust normal or default mutex types do not check the owner of +the mutex. For all types of robust mutexes the owner is checked and +an error code is returned if the calling thread does not own the +mutex.

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.

+[non-robust] 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

Robust Mutexes

If the mutex is PTHREAD_MUTEX_ROBUST and the owning thread +terminates without unlocking the mutex the implementation will wake +one waiting thread, if any. The next thread to acquire the mutex will +receive the error code EOWNERDEAD, +in which case that thread should if possible ensure that the state +protected by the mutex is consistent and then call +pthread_mutex_consistent before +unlocking. The mutex may then be used normally from then on.

If the thread cannot recover the +state then it must call pthread_mutex_unlock +without calling pthread_mutex_consistent. +This will mark the mutex as unusable and wake all currently waiting +threads with the return code ENOTRECOVERABLE. +The error indicates that the mutex is no longer usable and any +threads that receive this error code from any lock operation have not +acquired the mutex. The mutex can be made consistent by calling +pthread_mutex_destroy to +uninitialize the mutex, and calling pthread_mutex_int +to reinitialize the mutex. However, +the state that was protected by the mutex remains inconsistent and +some form of application recovery is required.

If a thread that receives the +EOWNERDEAD error code +itself terminates without unlocking the mutex then this behaviour +repeats for the next acquiring thread.

Applications must ensure that +they check the return values from all calls targeting robust mutexes.

Robust mutexes are slower because they +require some additional overhead, however they are not very much +slower than the non-robust recursive type.

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 @@ -138,46 +198,56 @@ 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 -: +
EINVAL: the mutex has not been properly initialized. -
- EDEADLK -: +
+ 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: -

+ The pthread_mutex_trylock function returns the following + error codes on error: +
+ EOWNERDEAD: + the robust mutex is now locked by the calling thread after the + previous owner terminated without unlocking it.
+ ENOTRECOVERABLE: + the robust mutex is not locked and is no longer usable after the + previous owner unlocked it without calling + pthread_mutex_consistent.

The pthread_mutex_timedlock function returns the following @@ -185,15 +255,22 @@ error codes on error:

+ EOWNERDEAD: + the robust mutex is now locked by the calling thread after the + previous owner terminated without unlocking it.
+ ENOTRECOVERABLE: + the robust mutex is not locked and is no longer usable after the + previous owner unlocked it without calling + pthread_mutex_consistent.

The pthread_mutex_unlock function returns the following error @@ -201,12 +278,12 @@ code on error:

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

@@ -217,61 +294,63 @@ code on error:

EBUSY -: +
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;

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);
+pthread_mutex_lock(&mut);
 /* operate on x */
 pthread_mutex_unlock(&mut);
 
-Table of
-Contents
+Table
+of Contents
 
-	Name
+	Name
 		
-	
Synopsis
+	Synopsis
 		
-	
Description
+	Description
 		
-	
Cancellation
+	Robust
+	Mutexes
+	
Cancellation
 		
-	
Async-signal
+	Async-signal
 	Safety 
 	
-	
Return
+	Return
 	Value 
 	
-	
Errors
+	Errors
 		
-	
Author
+	Author
 		
-	
See
+	See
 	Also 
 	
-	
Example
+	Example
 		
 
 
-
+
\ No newline at end of file
-- 
cgit v1.2.3