Ubuntu Manpage: pthread_mutex_init, pthread_mutex_lock, pthread_mutex

Provided by: glibc-doc_2.3.6-0ubuntu20_all

NAME

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

SYNOPSIS

       #include <pthread.h>

       pthread_mutex_t fastmutex = PTHREAD_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_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.

The LinuxThreads implementation supports only one mutex attributes, the
|mutex kind|, which is either ‘‘fast’’, ‘‘recursive’’, or ‘‘error
checking’’. The kind of a mutex determines whether it can be locked
again by a thread that already owns it. The default kind is ‘‘fast’’.
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 fast mutexes),
!PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP! (for recursive mutexes), and
!PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP! (for error checking mutexes).

!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 kind of the mutex. If the mutex is
of the ‘‘fast’’ kind, 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’’ kind, !pthread_mutex_lock!
returns immediately with the error code !EDEADLK!. If the mutex is of
the ‘‘recursive’’ kind, !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 ‘‘fast’’ mutex). Instead, !pthread_mutex_trylock! returns
immediately with the error code !EBUSY!.

!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 ‘‘fast’’ kind,
!pthread_mutex_unlock! always returns it to the unlocked state. If it
is of the ‘‘recursive’’ kind, 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. ‘‘Fast’’ and ‘‘recursive’’ 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 must not be
relied upon.

!pthread_mutex_destroy! destroys a mutex object, freeing the resources
it might hold. The mutex must be unlocked on entrance. In the
LinuxThreads implementation, no resources are associated with mutex
objects, thus !pthread_mutex_destroy! actually does nothing except
checking that the mutex is unlocked.

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

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);

                                 LinuxThreads                 PTHREAD_MUTEX(3)

Ubuntu manuals