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.Dd February 6, 2010 29.Dt MTX_POOL 9 30.Os 31.Sh NAME 32.Nm mtx_pool , 33.Nm mtx_pool_alloc , 34.Nm mtx_pool_find , 35.Nm mtx_pool_lock , 36.Nm mtx_pool_lock_spin , 37.Nm mtx_pool_unlock , 38.Nm mtx_pool_unlock_spin , 39.Nm mtx_pool_create , 40.Nm mtx_pool_destroy 41.Nd "mutex pool routines" 42.Sh SYNOPSIS 43.In sys/param.h 44.In sys/lock.h 45.In sys/mutex.h 46.Ft "struct mtx *" 47.Fn mtx_pool_alloc "struct mtx_pool *pool" 48.Ft "struct mtx *" 49.Fn mtx_pool_find "struct mtx_pool *pool" "void *ptr" 50.Ft void 51.Fn mtx_pool_lock "struct mtx_pool *pool" "void *ptr" 52.Ft void 53.Fn mtx_pool_lock_spin "struct mtx_pool *pool" "void *ptr" 54.Ft void 55.Fn mtx_pool_unlock "struct mtx_pool *pool" "void *ptr" 56.Ft void 57.Fn mtx_pool_unlock_spin "struct mtx_pool *pool" "void *ptr" 58.Ft "struct mtx_pool *" 59.Fn mtx_pool_create "const char *mtx_name" "int pool_size" "int opts" 60.Ft "void" 61.Fn mtx_pool_destroy "struct mtx_pool **poolp" 62.Sh DESCRIPTION 63Mutex pools are designed to be used as short term leaf mutexes; 64i.e., the last mutex one might acquire before calling 65.Xr mtx_sleep 9 . 66They operate using a shared pool of mutexes. 67A mutex may be chosen from the pool based on a supplied pointer, 68which may or may not point to anything valid, 69or the caller may allocate an arbitrary shared mutex from the pool 70and save the returned mutex pointer for later use. 71.Pp 72The shared mutexes in the 73.Va mtxpool_sleep 74mutex pool, 75which is created by default, 76are standard, non-recursive, 77blockable mutexes, and should only be used in appropriate situations. 78The mutexes in the 79.Va mtxpool_lockbuilder 80mutex pool are similar, except that they are initialized with the MTX_NOWITNESS 81flag so that they may be used to build higher-level locks. 82Other mutex pools may be created that contain mutexes with different 83properties, such as spin mutexes. 84.Pp 85The caller can lock and unlock mutexes returned by the pool routines, but 86since the mutexes are shared, the caller should not attempt to destroy them 87or modify their characteristics. 88While pool mutexes are normally leaf mutexes 89(meaning that one cannot depend on any ordering guarantees 90after obtaining one), 91one can still obtain other mutexes under carefully controlled circumstances. 92Specifically, if one has a private mutex 93(one that was allocated and initialized by the caller), 94one can obtain it after obtaining a pool mutex if ordering issues are 95carefully accounted for. 96In these cases the private mutex winds up being the true leaf mutex. 97.Pp 98Pool mutexes have the following advantages: 99.Pp 100.Bl -enum -offset indent -compact 101.It 102No structural overhead; 103i.e., they can be associated with a structure without adding bloat to it. 104.It 105Mutexes can be obtained for invalid pointers, which is useful when one uses 106mutexes to interlock destructor operations. 107.It 108No initialization or destruction overhead. 109.It 110Can be used with 111.Xr mtx_sleep 9 . 112.El 113.Pp 114And the following disadvantages: 115.Pp 116.Bl -enum -offset indent -compact 117.It 118Should generally only be used as leaf mutexes. 119.It 120Pool/pool dependency ordering cannot be guaranteed. 121.It 122Possible L1 cache mastership contention between CPUs. 123.El 124.Pp 125.Fn mtx_pool_alloc 126obtains a shared mutex from the specified pool. 127This routine uses a simple rover to choose one of the shared mutexes managed 128by the 129.Nm 130subsystem. 131.Pp 132.Fn mtx_pool_find 133returns the shared mutex associated with the specified address. 134This routine will create a hash out of the pointer passed into it 135and will choose a shared mutex from the specified pool based on that hash. 136The pointer does not need to point to anything real. 137.Pp 138.Fn mtx_pool_lock , 139.Fn mtx_pool_lock_spin , 140.Fn mtx_pool_unlock , 141and 142.Fn mtx_pool_unlock_spin 143lock and unlock the shared mutex from the specified pool 144associated with the specified address; 145they are a combination of 146.Fn mtx_pool_find 147and 148.Xr mtx_lock 9 , 149.Xr mtx_lock_spin 9 , 150.Xr mtx_unlock 9 , 151and 152.Xr mtx_unlock_spin 9 , 153respectively. 154Since these routines must first find the mutex to operate on, 155they are not as fast as directly using the mutex pointer returned by 156a previous invocation of 157.Fn mtx_pool_find 158or 159.Fn mtx_pool_alloc . 160.Pp 161.Fn mtx_pool_create 162allocates and initializes a new mutex pool of the 163specified size. 164The pool size must be a power of two. 165The 166.Fa opts 167argument is passed to 168.Xr mtx_init 9 169to set the options for each mutex in the pool. 170.Pp 171.Fn mtx_pool_destroy 172calls 173.Xr mtx_destroy 9 174on each mutex in the specified pool, 175deallocates the memory associated with the pool, 176and assigns NULL to the pool pointer. 177.Sh SEE ALSO 178.Xr locking 9 , 179.Xr mutex 9 180.Sh HISTORY 181These routines first appeared in 182.Fx 5.0 . 183