| blob | 677bee08e0f216eca8f6cbd1be8ef7a66e8e9a3f |
1 .\"
2 .\" This file and its contents are supplied under the terms of the
3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
4 .\" You may only use this file in accordance with the terms of version
5 .\" 1.0 of the CDDL.
6 .\"
7 .\" A full copy of the text of the CDDL should have accompanied this
8 .\" source. A copy of the CDDL is also available via the Internet at
9 .\" http://www.illumos.org/license/CDDL.
10 .\"
11 .\"
12 .\" Copyright 2016 Joyent, Inc.
13 .\"
14 .Dd "Jan 11, 2015"
15 .Dt MTX 3C
16 .Os
17 .Sh NAME
18 .Nm mtx ,
19 .Nm mtx_destroy ,
20 .Nm mtx_init ,
21 .Nm mtx_lock ,
22 .Nm mtx_timedlock ,
23 .Nm mtx_trylock ,
24 .Nm mtx_unlock
25 .Nd C11 mutex operations
26 .Sh SYNOPSIS
27 .In threads.h
28 .Ft int
29 .Fo mtx_init
30 .Fa "mtx_t *mtx"
31 .Fa "int type"
32 .Fc
33 .Ft void
34 .Fo mtx_destroy
35 .Fa "mtx_t *mtx"
36 .Fc
37 .Ft int
38 .Fo mtx_lock
39 .Fa "mtx_t *mtx"
40 .Fc
41 .Ft int
42 .Fo mtx_timedlock
43 .Fa "mtx_t *mtx"
44 .Fa "const struct timespec *restrict ts"
45 .Fc
46 .Ft int
47 .Fo mtx_trylock
48 .Fa "mtx_t *mtx"
49 .Fc
50 .Ft int
51 .Fo mtx_unlock
52 .Fa "mtx_t *mtx"
53 .Fc
54 .Sh DESCRIPTION
55 The
56 .Sy mtx
57 family of functions implement mutual exclusion locks (mutexes) and behave
58 similarly to both POSIX threads and illumos threads; however, they have
59 slightly different call signatures and return values.
60 For more information, see
61 .Xr threads 5 .
62 Importantly, they do not allow for inter-process synchronization.
63 .Ss Creating and Destroying Mutexes
64 The
65 .Fn mtx_init
66 function initializes the mutex specified by
67 .Fa mtx .
68 The following types of mutexes are valid and may be specified by the
69 .Fa type
70 argument:
71 .Bl -tag -width Dv
72 .It Sy mtx_plain
73 A simple, intra-process mutex.
74 .It Sy mtx_timed
75 A simple, intra-process mutex, which allows timed locking operations.
76 .It Sy mtx_plain | mtx_recursive
77 An intra-process mutex that may be acquired recursively by the same
78 thread.
79 It must be unlocked an equal number of times that it is locked.
80 .It Sy mtx_timed | mtx_recursive
81 An intra-process mutex that supports timed locking operations and may be
82 acquired recursively by the same thread.
83 It must be unlocked an equal number of times that it is locked.
84 .El
85 For more information on the different kind of mutexes, see
86 .Xr mutex_init 3C .
87 .Pp
88 The
89 .Fn mtx_destroy
90 function destroys the mutex pointed to by
91 .Fa mtx .
92 It is illegal for threads to be blocked waiting for
93 .Fa mtx
94 when
95 .Fn mtx_destroy
96 is called .
97 .Ss Locking and Unlocking Mutexes
98 The
99 .Fn mtx_lock
100 function attempts to lock the mutex
101 .Fa mtx .
102 When the function returns, it will be the sole owner of the mutex and
103 must call
104 .Fn mtx_unlock
105 when it is done, or risk inducing a deadlock in the process.
106 Other threads that make calls to
107 .Fn mtx_lock
108 after another thread has successfully completed its call to
109 .Fn mtx_lock
110 will block.
111 When they finally return, then they will have obtained the mutex
112 .Fa mtx .
113 .Pp
114 Unless a lock of type
115 .Sy mtx_recursive
116 was created, a thread calling
117 .Fn mtx_lock
118 when it already holds
119 .Fa mtx
120 will cause the thread to deadlock.
121 Othewrise, the lock will be successfully taken again.
122 However, a thread must call
123 .Fn mtx_unlock
124 for each time that it has acquried
125 .Fa mtx .
126 .Pp
127 The
128 .Fn mtx_trylock
129 function will attempt to obtain the mutex pointed to by
130 .Fa mtx .
131 However, unlike
132 .Fn mtx_lock ,
133 if
134 .Fa mtx
135 is locked, then it will not block and wait for
136 .Fa mtx
137 and instead return
138 .Sy thrd_busy
139 to indicate that the lock is currently held.
140 .Pp
141 The
142 .Fn mtx_timedlock
143 function attempts to obtain the mutex pointed to by
144 .Fa mtx .
145 If it is unable to obtain it, then it will block for a set amount of
146 time dictated by
147 .Fa ts .
148 The timeout in
149 .Fa ts
150 is treated as an absolute time in UTC to block until, measured based on
151 the
152 .Sy CLOCK_REALTIME
153 clock.
154 .Pp
155 The
156 .Fn mtx_unlock
157 function unlocks the mutex pointed to by
158 .Fa mtx ,
159 which allows another thread the opportunity to obtain it.
160 If any threads are actively blocking on the mutex, one of them will obtain it
161 and be woken up.
162 It is an error to call
163 .Fn mtx_unlock
164 on a mutex which the calling thread does not currently own.
165 .Sh RETURN VALUES
166 Upon successful completion, the function
167 .Fn mtx_init returns
168 .Sy thrd_success.
169 If there was insufficient memory to create the thread,
170 it instead returns
171 .Sy thrd_nomem .
172 If any other error occurred, it returns
173 .Sy thrd_error .
174 .Pp
175 The functions
176 .Fn mtx_lock ,
177 and
178 .Fn mtx_unlock
179 return
180 .Sy thrd_success .
181 If they were unable to successfully complete the operation, they instead
182 return
183 .Sy thrd_error .
184 .Pp
185 Upon successful completion, the
186 .Fn mtx_timedlock
187 function returns
188 .Sy thrd_success .
189 If the timeout is reached and the calling thread is unable to obtain the
190 mutex, then
191 .Sy thrd_timedout
192 is returned .
193 If any other error occurs, then
194 .Sy thrd_error is returned.
195 .Pp
196 Upon successful completion, the
197 .Fn mtx_trylock
198 function returns
199 .Sy thrd_success .
200 If the thread was unable to obtain the mutex because another thread owns
201 it, then it returns
202 .Sy thrd_busy .
203 Otherwise, an error will have occurred and
204 .Sy thrd_error
205 is returned.
206 .Sh INTERFACE STABILITY
207 .Sy Standard
208 .Sh MT-LEVEL
209 .Sy MT-Safe
210 .Sh SEE ALSO
211 .Xr mutex_init 3C ,
212 .Xr pthread_mutex_destroy 3C ,
213 .Xr pthread_mutex_init 3C ,
214 .Xr pthread_mutex_lock 3C ,
215 .Xr pthread_mutex_timedlock 3C ,
216 .Xr pthread_mutex_trylock 3C ,
217 .Xr pthread_mutex_unlock 3C ,
218 .Xr threads.h 3HEAD ,
219 .Xr attributes 5