1fc2512cfSRobert Mustacchi.\" 2fc2512cfSRobert Mustacchi.\" This file and its contents are supplied under the terms of the 3fc2512cfSRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 4fc2512cfSRobert Mustacchi.\" You may only use this file in accordance with the terms of version 5fc2512cfSRobert Mustacchi.\" 1.0 of the CDDL. 6fc2512cfSRobert Mustacchi.\" 7fc2512cfSRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 8fc2512cfSRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 9fc2512cfSRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 10fc2512cfSRobert Mustacchi.\" 11fc2512cfSRobert Mustacchi.\" 12fc2512cfSRobert Mustacchi.\" Copyright 2016 Joyent, Inc. 13fc2512cfSRobert Mustacchi.\" 1494494656SRobert Mustacchi.Dd "February 14, 2020" 15fc2512cfSRobert Mustacchi.Dt MTX 3C 16fc2512cfSRobert Mustacchi.Os 17fc2512cfSRobert Mustacchi.Sh NAME 18fc2512cfSRobert Mustacchi.Nm mtx , 19fc2512cfSRobert Mustacchi.Nm mtx_destroy , 20fc2512cfSRobert Mustacchi.Nm mtx_init , 21fc2512cfSRobert Mustacchi.Nm mtx_lock , 22fc2512cfSRobert Mustacchi.Nm mtx_timedlock , 23fc2512cfSRobert Mustacchi.Nm mtx_trylock , 24fc2512cfSRobert Mustacchi.Nm mtx_unlock 25fc2512cfSRobert Mustacchi.Nd C11 mutex operations 26fc2512cfSRobert Mustacchi.Sh SYNOPSIS 27fc2512cfSRobert Mustacchi.In threads.h 28fc2512cfSRobert Mustacchi.Ft int 29fc2512cfSRobert Mustacchi.Fo mtx_init 30fc2512cfSRobert Mustacchi.Fa "mtx_t *mtx" 31fc2512cfSRobert Mustacchi.Fa "int type" 32fc2512cfSRobert Mustacchi.Fc 33fc2512cfSRobert Mustacchi.Ft void 34fc2512cfSRobert Mustacchi.Fo mtx_destroy 35fc2512cfSRobert Mustacchi.Fa "mtx_t *mtx" 36fc2512cfSRobert Mustacchi.Fc 37fc2512cfSRobert Mustacchi.Ft int 38fc2512cfSRobert Mustacchi.Fo mtx_lock 39fc2512cfSRobert Mustacchi.Fa "mtx_t *mtx" 40fc2512cfSRobert Mustacchi.Fc 41fc2512cfSRobert Mustacchi.Ft int 42fc2512cfSRobert Mustacchi.Fo mtx_timedlock 43fc2512cfSRobert Mustacchi.Fa "mtx_t *mtx" 44fc2512cfSRobert Mustacchi.Fa "const struct timespec *restrict ts" 45fc2512cfSRobert Mustacchi.Fc 46fc2512cfSRobert Mustacchi.Ft int 47fc2512cfSRobert Mustacchi.Fo mtx_trylock 48fc2512cfSRobert Mustacchi.Fa "mtx_t *mtx" 49fc2512cfSRobert Mustacchi.Fc 50fc2512cfSRobert Mustacchi.Ft int 51fc2512cfSRobert Mustacchi.Fo mtx_unlock 52fc2512cfSRobert Mustacchi.Fa "mtx_t *mtx" 53fc2512cfSRobert Mustacchi.Fc 54fc2512cfSRobert Mustacchi.Sh DESCRIPTION 55fc2512cfSRobert MustacchiThe 56fc2512cfSRobert Mustacchi.Sy mtx 57fc2512cfSRobert Mustacchifamily of functions implement mutual exclusion locks (mutexes) and behave 58fc2512cfSRobert Mustacchisimilarly to both POSIX threads and illumos threads; however, they have 5972d3dbb9SYuri Pankovslightly different call signatures and return values. 6072d3dbb9SYuri PankovFor more information, see 61*bbf21555SRichard Lowe.Xr threads 7 . 62fc2512cfSRobert MustacchiImportantly, they do not allow for inter-process synchronization. 63fc2512cfSRobert Mustacchi.Ss Creating and Destroying Mutexes 64fc2512cfSRobert MustacchiThe 65fc2512cfSRobert Mustacchi.Fn mtx_init 66fc2512cfSRobert Mustacchifunction initializes the mutex specified by 67fc2512cfSRobert Mustacchi.Fa mtx . 68fc2512cfSRobert MustacchiThe following types of mutexes are valid and may be specified by the 69fc2512cfSRobert Mustacchi.Fa type 70fc2512cfSRobert Mustacchiargument: 71fc2512cfSRobert Mustacchi.Bl -tag -width Dv 7294494656SRobert Mustacchi.It Dv mtx_plain 73fc2512cfSRobert MustacchiA simple, intra-process mutex. 7494494656SRobert Mustacchi.It Dv mtx_timed 75fc2512cfSRobert MustacchiA simple, intra-process mutex, which allows timed locking operations. 7694494656SRobert Mustacchi.It Dv mtx_plain | mtx_recursive 77fc2512cfSRobert MustacchiAn intra-process mutex that may be acquired recursively by the same 7872d3dbb9SYuri Pankovthread. 7972d3dbb9SYuri PankovIt must be unlocked an equal number of times that it is locked. 8094494656SRobert Mustacchi.It Dv mtx_timed | mtx_recursive 81fc2512cfSRobert MustacchiAn intra-process mutex that supports timed locking operations and may be 8272d3dbb9SYuri Pankovacquired recursively by the same thread. 8372d3dbb9SYuri PankovIt must be unlocked an equal number of times that it is locked. 84fc2512cfSRobert Mustacchi.El 85fc2512cfSRobert MustacchiFor more information on the different kind of mutexes, see 86fc2512cfSRobert Mustacchi.Xr mutex_init 3C . 87fc2512cfSRobert Mustacchi.Pp 88fc2512cfSRobert MustacchiThe 89fc2512cfSRobert Mustacchi.Fn mtx_destroy 90fc2512cfSRobert Mustacchifunction destroys the mutex pointed to by 91fc2512cfSRobert Mustacchi.Fa mtx . 92fc2512cfSRobert MustacchiIt is illegal for threads to be blocked waiting for 93fc2512cfSRobert Mustacchi.Fa mtx 94fc2512cfSRobert Mustacchiwhen 95fc2512cfSRobert Mustacchi.Fn mtx_destroy 96fc2512cfSRobert Mustacchiis called . 97fc2512cfSRobert Mustacchi.Ss Locking and Unlocking Mutexes 98fc2512cfSRobert MustacchiThe 99fc2512cfSRobert Mustacchi.Fn mtx_lock 100fc2512cfSRobert Mustacchifunction attempts to lock the mutex 101fc2512cfSRobert Mustacchi.Fa mtx . 102fc2512cfSRobert MustacchiWhen the function returns, it will be the sole owner of the mutex and 103fc2512cfSRobert Mustacchimust call 104fc2512cfSRobert Mustacchi.Fn mtx_unlock 10572d3dbb9SYuri Pankovwhen it is done, or risk inducing a deadlock in the process. 10672d3dbb9SYuri PankovOther threads that make calls to 107fc2512cfSRobert Mustacchi.Fn mtx_lock 108fc2512cfSRobert Mustacchiafter another thread has successfully completed its call to 109fc2512cfSRobert Mustacchi.Fn mtx_lock 110fc2512cfSRobert Mustacchiwill block. 111fc2512cfSRobert MustacchiWhen they finally return, then they will have obtained the mutex 112fc2512cfSRobert Mustacchi.Fa mtx . 113fc2512cfSRobert Mustacchi.Pp 114fc2512cfSRobert MustacchiUnless a lock of type 11594494656SRobert Mustacchi.Dv mtx_recursive 116fc2512cfSRobert Mustacchiwas created, a thread calling 117fc2512cfSRobert Mustacchi.Fn mtx_lock 118fc2512cfSRobert Mustacchiwhen it already holds 119fc2512cfSRobert Mustacchi.Fa mtx 12072d3dbb9SYuri Pankovwill cause the thread to deadlock. 12194494656SRobert MustacchiOtherwise, the lock will be successfully taken again. 12272d3dbb9SYuri PankovHowever, a thread must call 123fc2512cfSRobert Mustacchi.Fn mtx_unlock 12494494656SRobert Mustacchifor each time that it has acquired 125fc2512cfSRobert Mustacchi.Fa mtx . 126fc2512cfSRobert Mustacchi.Pp 127fc2512cfSRobert MustacchiThe 128fc2512cfSRobert Mustacchi.Fn mtx_trylock 129fc2512cfSRobert Mustacchifunction will attempt to obtain the mutex pointed to by 130fc2512cfSRobert Mustacchi.Fa mtx . 131fc2512cfSRobert MustacchiHowever, unlike 132fc2512cfSRobert Mustacchi.Fn mtx_lock , 133fc2512cfSRobert Mustacchiif 134fc2512cfSRobert Mustacchi.Fa mtx 135fc2512cfSRobert Mustacchiis locked, then it will not block and wait for 136fc2512cfSRobert Mustacchi.Fa mtx 137fc2512cfSRobert Mustacchiand instead return 13894494656SRobert Mustacchi.Dv thrd_busy 139fc2512cfSRobert Mustacchito indicate that the lock is currently held. 140fc2512cfSRobert Mustacchi.Pp 141fc2512cfSRobert MustacchiThe 142fc2512cfSRobert Mustacchi.Fn mtx_timedlock 143fc2512cfSRobert Mustacchifunction attempts to obtain the mutex pointed to by 144fc2512cfSRobert Mustacchi.Fa mtx . 145fc2512cfSRobert MustacchiIf it is unable to obtain it, then it will block for a set amount of 146fc2512cfSRobert Mustacchitime dictated by 147fc2512cfSRobert Mustacchi.Fa ts . 148fc2512cfSRobert MustacchiThe timeout in 149fc2512cfSRobert Mustacchi.Fa ts 150fc2512cfSRobert Mustacchiis treated as an absolute time in UTC to block until, measured based on 151fc2512cfSRobert Mustacchithe 15294494656SRobert Mustacchi.Dv CLOCK_REALTIME 153fc2512cfSRobert Mustacchiclock. 154fc2512cfSRobert Mustacchi.Pp 155fc2512cfSRobert MustacchiThe 156fc2512cfSRobert Mustacchi.Fn mtx_unlock 157fc2512cfSRobert Mustacchifunction unlocks the mutex pointed to by 158fc2512cfSRobert Mustacchi.Fa mtx , 15972d3dbb9SYuri Pankovwhich allows another thread the opportunity to obtain it. 16072d3dbb9SYuri PankovIf any threads are actively blocking on the mutex, one of them will obtain it 16172d3dbb9SYuri Pankovand be woken up. 16272d3dbb9SYuri PankovIt is an error to call 163fc2512cfSRobert Mustacchi.Fn mtx_unlock 164fc2512cfSRobert Mustacchion a mutex which the calling thread does not currently own. 165fc2512cfSRobert Mustacchi.Sh RETURN VALUES 166fc2512cfSRobert MustacchiUpon successful completion, the function 16794494656SRobert Mustacchi.Fn mtx_init 16894494656SRobert Mustacchireturns 16994494656SRobert Mustacchi.Dv thrd_success . 170fc2512cfSRobert MustacchiIf there was insufficient memory to create the thread, 171fc2512cfSRobert Mustacchiit instead returns 17294494656SRobert Mustacchi.Dv thrd_nomem . 173fc2512cfSRobert MustacchiIf any other error occurred, it returns 17494494656SRobert Mustacchi.Dv thrd_error . 175fc2512cfSRobert Mustacchi.Pp 176fc2512cfSRobert MustacchiThe functions 177fc2512cfSRobert Mustacchi.Fn mtx_lock , 178fc2512cfSRobert Mustacchiand 179fc2512cfSRobert Mustacchi.Fn mtx_unlock 180fc2512cfSRobert Mustacchireturn 18194494656SRobert Mustacchi.Dv thrd_success . 182fc2512cfSRobert MustacchiIf they were unable to successfully complete the operation, they instead 183fc2512cfSRobert Mustacchireturn 18494494656SRobert Mustacchi.Dv thrd_error . 185fc2512cfSRobert Mustacchi.Pp 186bccbd30bSPeter TribbleUpon successful completion, the 187fc2512cfSRobert Mustacchi.Fn mtx_timedlock 188fc2512cfSRobert Mustacchifunction returns 18994494656SRobert Mustacchi.Dv thrd_success . 190fc2512cfSRobert MustacchiIf the timeout is reached and the calling thread is unable to obtain the 191fc2512cfSRobert Mustacchimutex, then 19294494656SRobert Mustacchi.Dv thrd_timedout 193fc2512cfSRobert Mustacchiis returned. 194fc2512cfSRobert MustacchiIf any other error occurs, then 19594494656SRobert Mustacchi.Dv thrd_error 19694494656SRobert Mustacchiis returned. 197fc2512cfSRobert Mustacchi.Pp 198fc2512cfSRobert MustacchiUpon successful completion, the 199fc2512cfSRobert Mustacchi.Fn mtx_trylock 200fc2512cfSRobert Mustacchifunction returns 20194494656SRobert Mustacchi.Dv thrd_success . 202fc2512cfSRobert MustacchiIf the thread was unable to obtain the mutex because another thread owns 203fc2512cfSRobert Mustacchiit, then it returns 20494494656SRobert Mustacchi.Dv thrd_busy . 205fc2512cfSRobert MustacchiOtherwise, an error will have occurred and 20694494656SRobert Mustacchi.Dv thrd_error 207fc2512cfSRobert Mustacchiis returned. 208fc2512cfSRobert Mustacchi.Sh INTERFACE STABILITY 209fc2512cfSRobert Mustacchi.Sy Standard 210fc2512cfSRobert Mustacchi.Sh MT-LEVEL 211fc2512cfSRobert Mustacchi.Sy MT-Safe 212fc2512cfSRobert Mustacchi.Sh SEE ALSO 213fc2512cfSRobert Mustacchi.Xr mutex_init 3C , 214fc2512cfSRobert Mustacchi.Xr pthread_mutex_destroy 3C , 215fc2512cfSRobert Mustacchi.Xr pthread_mutex_init 3C , 216fc2512cfSRobert Mustacchi.Xr pthread_mutex_lock 3C , 217fc2512cfSRobert Mustacchi.Xr pthread_mutex_timedlock 3C , 218fc2512cfSRobert Mustacchi.Xr pthread_mutex_trylock 3C , 219fc2512cfSRobert Mustacchi.Xr pthread_mutex_unlock 3C , 220fc2512cfSRobert Mustacchi.Xr threads.h 3HEAD , 221*bbf21555SRichard Lowe.Xr attributes 7 222