]>
Commit | Line | Data |
---|---|---|
5afdca00 UD |
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 | ||
79996eee | 22 | int pthread_mutex_lock(pthread_mutex_t *mutex); |
5afdca00 UD |
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 |