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