1.\" $OpenBSD: mutex.9,v 1.22 2014/02/13 14:23:05 jmc Exp $ 2.\" 3.\" Copyright (c) 2005 Pedro Martelletto <pedro@ambientworks.net> 4.\" All rights reserved. 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: February 13 2014 $ 19.Dt MUTEX 9 20.Os 21.Sh NAME 22.Nm mutex , 23.Nm mtx_init , 24.Nm mtx_enter , 25.Nm mtx_enter_try , 26.Nm mtx_leave , 27.Nm MUTEX_ASSERT_LOCKED , 28.Nm MUTEX_ASSERT_UNLOCKED , 29.Nm MUTEX_INITIALIZER 30.Nd interface to CPU mutexes 31.Sh SYNOPSIS 32.In sys/mutex.h 33.Ft void 34.Fn mtx_init "struct mutex *mtxp" "int wantipl" 35.Ft void 36.Fn mtx_enter "struct mutex *mtxp" 37.Ft int 38.Fn mtx_enter_try "struct mutex *mtxp" 39.Ft void 40.Fn mtx_leave "struct mutex *mtxp" 41.Fn MUTEX_ASSERT_LOCKED "struct mutex *mtxp" 42.Fn MUTEX_ASSERT_UNLOCKED "struct mutex *mtxp" 43.Fn MUTEX_INITIALIZER "int wantipl" 44.Sh DESCRIPTION 45The 46.Nm 47set of functions provides a non-recursive, interrupt-aware spinning mechanism 48to ensure mutual exclusion between different CPUs. 49.Pp 50The 51.Fn mtx_init 52function is used to initiate the mutex pointed to by 53.Fa mtxp . 54When acquired, the mutex will cause the processor interrupt level to be raised 55to 56.Fa wantipl 57if necessary. 58.Pp 59The 60.Fn mtx_enter 61function acquires a mutex, spinning if necessary. 62.Pp 63The 64.Fn mtx_enter_try 65function attempts to acquire a mutex. 66.Pp 67The 68.Fn mtx_leave 69function releases a mutex. 70In case the acquisition of the mutex caused the interrupt level to be changed, 71it is then restored. 72.Pp 73The 74.Fn MUTEX_ASSERT_LOCKED 75and 76.Fn MUTEX_ASSERT_UNLOCKED 77macros may be used to assert that a mutex is held locked or unlocked by 78the current CPU. 79.Pp 80A mutex declaration may be initialised with the 81.Fn MUTEX_INITIALIZER 82macro. 83When acquired, the mutex will cause the processor interrupt level to be raised 84to 85.Fa wantipl 86if necessary. 87.Sh CONTEXT 88.Fn mtx_init 89can be called during autoconf, from process context, or from interrupt 90context. 91.Pp 92.Fn mtx_enter , 93.Fn mtx_enter_try , 94and 95.Fn mtx_leave 96can be called during autoconf, from process context, or from any 97interrupt context at or below the interrupt level 98.Fa mtxp 99was initialised with. 100.Sh RETURN VALUES 101The 102.Fn mtx_enter_try 103function will return non-zero if it succeeds in acquiring the mutex 104.Fa mtxp , 105otherwise it will return 0. 106.Sh SEE ALSO 107.Xr lockmgr 9 , 108.Xr msleep 9 , 109.Xr rwlock 9 , 110.Xr spl 9 111.Sh HISTORY 112The 113.Nm 114functions first appeared in 115.Ox 3.6 . 116.Sh AUTHORS 117The 118.Nm 119functions were written by 120.An Artur Grabowski Aq Mt art@openbsd.org . 121.Sh CAVEATS 122As these are spinning locks, don't sleep while holding one. 123.Pp 124Multiple mutexes may be nested, but not interleaved. 125This is okay: 126.Bd -literal -offset indent 127mtx_enter(foo); 128mtx_enter(bar); 129mtx_leave(bar); 130mtx_leave(foo); 131.Ed 132.Pp 133While this is 134.Fa not : 135.Bd -literal -offset indent 136mtx_enter(foo); 137mtx_enter(bar); 138mtx_leave(foo); 139mtx_leave(bar); 140.Ed 141