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_consistent, 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_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.

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.

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.

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� 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� 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. 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’’ [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.

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

See Also

pthread_mutexattr_init(3) , pthread_mutexattr_settype(3) , pthread_cancel(3) .

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