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