1.\" 2.\" Copyright (C) 2002 Garrett Rooney <rooneg@electricjellyfish.net>. 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice(s), this list of conditions and the following disclaimer as 10.\" the first lines of this file unmodified other than the possible 11.\" addition of one or more copyright notices. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice(s), this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 17.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 18.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 19.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY 20.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 21.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 22.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 23.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 26.\" DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd March 25, 2002 31.Dt MTX_POOL 9 32.Os 33.Sh NAME 34.Nm mtx_pool , 35.Nm mtx_pool_alloc , 36.Nm mtx_pool_find , 37.Nm mtx_pool_lock , 38.Nm mtx_pool_unlock 39.Nd "mutex pool routines" 40.Sh SYNOPSIS 41.In sys/param.h 42.In sys/lock.h 43.In sys/mutex.h 44.Ft "struct mtx *" 45.Fn mtx_pool_alloc "void" 46.Ft "struct mtx *" 47.Fn mtx_pool_find "void *ptr" 48.Ft void 49.Fn mtx_pool_lock "void *ptr" 50.Ft void 51.Fn mtx_pool_unlock "void *ptr" 52.Sh DESCRIPTION 53Mutex pools are designed to be used as short term leaf mutexes; 54i.e., the last mutex one might acquire before calling 55.Xr msleep 9 . 56They operate using a shared pool of mutexes. 57A mutex is chosen from the pool based on the supplied pointer, 58which may or may not point to anything valid. 59.Pp 60The shared mutexes managed by the pool module are standard, non-recursive, 61blockable mutexes, and should only be used in appropriate situations. 62.Pp 63The caller can lock and unlock mutexes returned by the pool routines, but 64since the mutexes are shared, the caller should not attempt to destroy them 65or modify their characteristics. 66While pool mutexes are normally leaf mutexes 67(meaning that one cannot depend on any ordering guarantees 68after obtaining one), 69one can still obtain other mutexes under carefully controlled circumstances. 70Specifically, if one has a private mutex 71(one that was allocated and initialized by the caller), 72one can obtain it after obtaining a pool mutex if ordering issues are 73carefully accounted for. 74In these cases the private mutex winds up being the true leaf mutex. 75.Pp 76Pool mutexes have the following advantages: 77.Pp 78.Bl -enum -offset indent -compact 79.It 80No structural overhead; 81i.e., they can be associated with a structure without adding bloat to it. 82.It 83Mutexes can be obtained for invalid pointers, which is useful when one uses 84mutexes to interlock destructor operations. 85.It 86No initialization or destruction overhead. 87.It 88Can be used with 89.Xr msleep 9 . 90.El 91.Pp 92And the following disadvantages: 93.Pp 94.Bl -enum -offset indent -compact 95.It 96Should generally only be used as leaf mutexes. 97.It 98Pool/pool dependency ordering cannot be guaranteed. 99.It 100Possible L1 cache mastership contention between CPUs. 101.El 102.Pp 103.Fn mtx_pool_alloc 104obtains a shared mutex from the pool. 105This routine uses a simple rover to choose one of the shared mutexes managed 106by the 107.Nm 108subsystem. 109.Pp 110.Fn mtx_pool_find 111returns the shared mutex associated with the specified address. 112This routine will create a hash out of the pointer passed into it 113and will choose a shared mutex based on that hash. 114The pointer does not need to point to anything real. 115.Pp 116.Fn mtx_pool_lock 117and 118.Fn mtx_pool_unlock 119lock and unlock the shared mutex associated with the specified address, 120respectively; 121they are a combination of 122.Fn mtx_pool_find 123and 124.Xr mtx_lock 9 125and 126.Xr mtx_unlock 9 , 127respectively. 128Since these routines must first find the mutex to operate on, 129they are not as fast as directly using the pointer (mutex) returned by 130a previous invocation of 131.Fn mtx_pool_find . 132.Pp 133.Sh SEE ALSO 134.Xr msleep 9 , 135.Xr mutex 9 136.Sh HISTORY 137These routines first appeared in 138.Fx 5.0 . 139