1.\" $OpenBSD: mutex.9,v 1.14 2010/08/08 12:39: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: August 8 2010 $ 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.Nd interface to CPU mutexes 28.Sh SYNOPSIS 29.Fd #include <sys/mutex.h> 30.Ft void 31.Fn mtx_init "struct mutex *mtxp" "int wantipl" 32.Ft void 33.Fn mtx_enter "struct mutex *mtxp" 34.Ft int 35.Fn mtx_enter_try "struct mutex *mtxp" 36.Ft void 37.Fn mtx_leave "struct mutex *mtxp" 38.Fn MUTEX_ASSERT_LOCKED "struct mutex *mtxp" 39.Fn MUTEX_ASSERT_UNLOCKED "struct mutex *mtxp" 40.Sh DESCRIPTION 41The 42.Nm 43set of functions provides a non-recursive, interrupt-aware spinning mechanism 44to ensure mutual exclusion between different CPUs. 45.Pp 46The 47.Fn mtx_init 48function is used to initiate the mutex pointed to by 49.Fa mtxp . 50When acquired, the mutex will cause the processor interrupt level to be raised 51to 52.Fa wantipl 53if necessary. 54.Pp 55The 56.Fn mtx_enter 57function acquires a mutex, spinning if necessary. 58.Pp 59The 60.Fn mtx_enter_try 61function attempts to acquire a mutex. 62If it succeeds in acquiring the mutex it will return non-zero, otherwise 63it will return 0. 64.Pp 65The 66.Fn mtx_leave 67function releases a mutex. 68In case the acquisition of the mutex caused the interrupt level to be changed, 69it is then restored. 70.Pp 71The 72.Fn MUTEX_ASSERT_LOCKED 73and 74.Fn MUTEX_ASSERT_UNLOCKED 75macros may be used to assert that a mutex is held locked or unlocked by 76the current CPU. 77.Sh SEE ALSO 78.Xr lockmgr 9 , 79.Xr rwlock 9 , 80.Xr spl 9 81.Sh HISTORY 82The 83.Nm 84functions first appeared in 85.Ox 3.6 . 86.Sh AUTHORS 87The 88.Nm 89functions were written by 90.An Artur Grabowski 91.Aq art@openbsd.org . 92.Sh CAVEATS 93As these are spinning locks, don't sleep while holding one. 94.Pp 95If using a mutex in an interrupt handler, locks must be initialised 96with the correct IPL or deadlock will occur. 97.Pp 98Multiple mutexes may be nested, but not interleaved. 99This is okay: 100.Bd -literal -offset indent 101mtx_enter(foo); 102mtx_enter(bar); 103mtx_leave(bar); 104mtx_leave(foo); 105.Ed 106.Pp 107While this is 108.Fa not : 109.Bd -literal -offset indent 110mtx_enter(foo); 111mtx_enter(bar); 112mtx_leave(foo); 113mtx_leave(bar); 114.Ed 115