linuxthreads/man/pthread_mutex_init.man

   1 .TH PTHREAD_MUTEX 3 LinuxThreads
   2
   3 .XREF pthread_mutex_lock
   4 .XREF pthread_mutex_unlock
   5 .XREF pthread_mutex_trylock
   6 .XREF pthread_mutex_destroy
   7
   8 .SH NAME
   9 pthread_mutex_init, pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock, pthread_mutex_destroy \- operations on mutexes
  10
  11 .SH SYNOPSIS
  12 #include <pthread.h>
  13
  14 pthread_mutex_t fastmutex = PTHREAD_MUTEX_INITIALIZER;
  15
  16 pthread_mutex_t recmutex = PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP;
  17
  18 pthread_mutex_t errchkmutex = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;
  19
  20 int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *mutexattr);
  21
  22 int pthread_mutex_lock(pthread_mutex_t *mutex);
  23
  24 int pthread_mutex_trylock(pthread_mutex_t *mutex);
  25
  26 int pthread_mutex_unlock(pthread_mutex_t *mutex);
  27
  28 int pthread_mutex_destroy(pthread_mutex_t *mutex);
  29
  30 .SH DESCRIPTION
  31 A mutex is a MUTual EXclusion device, and is useful for protecting
  32 shared data structures from concurrent modifications, and implementing
  33 critical sections and monitors.
  34
  35 A mutex has two possible states: unlocked (not owned by any thread),
  36 and locked (owned by one thread). A mutex can never be owned by two
  37 different threads simultaneously. A thread attempting to lock a mutex
  38 that is already locked by another thread is suspended until the owning
  39 thread unlocks the mutex first.
  40
  41 !pthread_mutex_init! initializes the mutex object pointed to by
  42 |mutex| according to the mutex attributes specified in |mutexattr|.
  43 If |mutexattr| is !NULL!, default attributes are used instead.
  44
  45 The LinuxThreads implementation supports only one mutex attributes,
  46 the |mutex kind|, which is either ``fast'', ``recursive'', or
  47 ``error checking''. The kind of a mutex determines whether
  48 it can be locked again by a thread that already owns it.
  49 The default kind is ``fast''. See !pthread_mutexattr_init!(3) for more
  50 information on mutex attributes.
  51
  52 Variables of type !pthread_mutex_t! can also be initialized
  53 statically, using the constants !PTHREAD_MUTEX_INITIALIZER! (for fast
  54 mutexes), !PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP! (for recursive
  55 mutexes), and !PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP! (for error checking
  56 mutexes).
  57
  58 !pthread_mutex_lock! locks the given mutex. If the mutex is currently
  59 unlocked, it becomes locked and owned by the calling thread, and
  60 !pthread_mutex_lock! returns immediately. If the mutex is already
  61 locked by another thread, !pthread_mutex_lock! suspends the calling
  62 thread until the mutex is unlocked.
  63
  64 If the mutex is already locked by the calling thread, the behavior of
  65 !pthread_mutex_lock! depends on the kind of the mutex. If the mutex is
  66 of the ``fast'' kind, the calling thread is suspended until the mutex
  67 is unlocked, thus effectively causing the calling thread to
  68 deadlock. If the mutex is of the ``error checking'' kind,
  69 !pthread_mutex_lock! returns immediately with the error code !EDEADLK!.
  70 If the mutex is of the ``recursive'' kind, !pthread_mutex_lock!
  71 succeeds and returns immediately, recording the number of times the
  72 calling thread has locked the mutex. An equal number of
  73 !pthread_mutex_unlock! operations must be performed before the mutex
  74 returns to the unlocked state.
  75
  76 !pthread_mutex_trylock! behaves identically to !pthread_mutex_lock!,
  77 except that it does not block the calling thread if the mutex is
  78 already locked by another thread (or by the calling thread in the case
  79 of a ``fast'' mutex). Instead, !pthread_mutex_trylock! returns
  80 immediately with the error code !EBUSY!.
  81
  82 !pthread_mutex_unlock! unlocks the given mutex. The mutex is assumed
  83 to be locked and owned by the calling thread on entrance to
  84 !pthread_mutex_unlock!. If the mutex is of the ``fast'' kind,
  85 !pthread_mutex_unlock! always returns it to the unlocked state. If it
  86 is of the ``recursive'' kind, it decrements the locking count of the
  87 mutex (number of !pthread_mutex_lock! operations performed on it by
  88 the calling thread), and only when this count reaches zero is the
  89 mutex actually unlocked.
  90
  91 On ``error checking'' mutexes, !pthread_mutex_unlock! actually checks
  92 at run-time that the mutex is locked on entrance, and that it was
  93 locked by the same thread that is now calling !pthread_mutex_unlock!.
  94 If these conditions are not met, an error code is returned and the
  95 mutex remains unchanged.  ``Fast'' and ``recursive'' mutexes perform
  96 no such checks, thus allowing a locked mutex to be unlocked by a
  97 thread other than its owner. This is non-portable behavior and must
  98 not be relied upon.
  99
 100 !pthread_mutex_destroy! destroys a mutex object, freeing the resources
 101 it might hold. The mutex must be unlocked on entrance. In the
 102 LinuxThreads implementation, no resources are associated with mutex
 103 objects, thus !pthread_mutex_destroy! actually does nothing except
 104 checking that the mutex is unlocked.
 105
 106 .SH CANCELLATION
 107
 108 None of the mutex functions is a cancellation point, not even
 109 !pthread_mutex_lock!, in spite of the fact that it can suspend a
 110 thread for arbitrary durations. This way, the status of mutexes at
 111 cancellation points is predictable, allowing cancellation handlers to
 112 unlock precisely those mutexes that need to be unlocked before the
 113 thread stops executing. Consequently, threads using deferred
 114 cancellation should never hold a mutex for extended periods of time.
 115
 116 .SH "ASYNC-SIGNAL SAFETY"
 117
 118 The mutex functions are not async-signal safe. What this means is that
 119 they should not be called from a signal handler. In particular,
 120 calling !pthread_mutex_lock! or !pthread_mutex_unlock! from a signal
 121 handler may deadlock the calling thread.
 122
 123 .SH "RETURN VALUE"
 124
 125 !pthread_mutex_init! always returns 0. The other mutex functions
 126 return 0 on success and a non-zero error code on error.
 127
 128 .SH ERRORS
 129
 130 The !pthread_mutex_lock! function returns the following error code
 131 on error:
 132 .RS
 133 .TP
 134 !EINVAL!
 135 the mutex has not been properly initialized.
 136
 137 .TP
 138 !EDEADLK!
 139 the mutex is already locked by the calling thread
 140 (``error checking'' mutexes only).
 141 .RE
 142
 143 The !pthread_mutex_trylock! function returns the following error codes
 144 on error:
 145 .RS
 146 .TP
 147 !EBUSY!
 148 the mutex could not be acquired because it was currently locked.
 149
 150 .TP
 151 !EINVAL!
 152 the mutex has not been properly initialized.
 153 .RE
 154
 155 The !pthread_mutex_unlock! function returns the following error code
 156 on error:
 157 .RS
 158 .TP
 159 !EINVAL!
 160 the mutex has not been properly initialized.
 161
 162 .TP
 163 !EPERM!
 164 the calling thread does not own the mutex (``error checking'' mutexes only).
 165 .RE
 166
 167 The !pthread_mutex_destroy! function returns the following error code
 168 on error:
 169 .RS
 170 .TP
 171 !EBUSY!
 172 the mutex is currently locked.
 173 .RE
 174
 175 .SH AUTHOR
 176 Xavier Leroy <Xavier.Leroy@inria.fr>
 177
 178 .SH "SEE ALSO"
 179 !pthread_mutexattr_init!(3),
 180 !pthread_mutexattr_setkind_np!(3),
 181 !pthread_cancel!(3).
 182
 183 .SH EXAMPLE
 184
 185 A shared global variable |x| can be protected by a mutex as follows:
 186
 187 .RS
 188 .ft 3
 189 .nf
 190 .sp
 191 int x;
 192 pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
 193 .ft
 194 .LP
 195 .RE
 196 .fi
 197
 198 All accesses and modifications to |x| should be bracketed by calls to
 199 !pthread_mutex_lock! and !pthread_mutex_unlock! as follows:
 200
 201 .RS
 202 .ft 3
 203 .nf
 204 .sp
 205 pthread_mutex_lock(&mut);
 206 /* operate on x */
 207 pthread_mutex_unlock(&mut);
 208 .ft
 209 .LP
 210 .RE
 211 .fi
 212
 213