2 .\" Copyright (C) 2002 Garrett Rooney <rooneg@electricjellyfish.net>.
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
38 .Nm mtx_pool_lock_spin ,
40 .Nm mtx_pool_unlock_spin ,
43 .Nd "mutex pool routines"
49 .Fn mtx_pool_alloc "struct mtx_pool *pool"
51 .Fn mtx_pool_find "struct mtx_pool *pool" "void *ptr"
53 .Fn mtx_pool_lock "struct mtx_pool *pool" "void *ptr"
55 .Fn mtx_pool_lock_spin "struct mtx_pool *pool" "void *ptr"
57 .Fn mtx_pool_unlock "struct mtx_pool *pool" "void *ptr"
59 .Fn mtx_pool_unlock_spin "struct mtx_pool *pool" "void *ptr"
60 .Ft "struct mtx_pool *"
61 .Fn mtx_pool_create "const char *mtx_name" "int pool_size" "int opts"
63 .Fn mtx_pool_destroy "struct mtx_pool **poolp"
65 Mutex pools are designed to be used as short term leaf mutexes;
66 i.e., the last mutex one might acquire before calling
68 They operate using a shared pool of mutexes.
69 A mutex may be chosen from the pool based on a supplied pointer,
70 which may or may not point to anything valid,
71 or the caller may allocate an arbitrary shared mutex from the pool
72 and save the returned mutex pointer for later use.
74 The shared mutexes in the
77 which is created by default,
78 are standard, non-recursive,
79 blockable mutexes, and should only be used in appropriate situations.
81 .Va mtxpool_lockbuilder
82 mutex pool are similar, except that they are initialized with the MTX_NOWITNESS
83 flag so that they may be used to build higher-level locks.
84 Other mutex pools may be created that contain mutexes with different
85 properties, such as spin mutexes.
87 The caller can lock and unlock mutexes returned by the pool routines, but
88 since the mutexes are shared, the caller should not attempt to destroy them
89 or modify their characteristics.
90 While pool mutexes are normally leaf mutexes
91 (meaning that one cannot depend on any ordering guarantees
93 one can still obtain other mutexes under carefully controlled circumstances.
94 Specifically, if one has a private mutex
95 (one that was allocated and initialized by the caller),
96 one can obtain it after obtaining a pool mutex if ordering issues are
97 carefully accounted for.
98 In these cases the private mutex winds up being the true leaf mutex.
100 Pool mutexes have the following advantages:
102 .Bl -enum -offset indent -compact
104 No structural overhead;
105 i.e., they can be associated with a structure without adding bloat to it.
107 Mutexes can be obtained for invalid pointers, which is useful when one uses
108 mutexes to interlock destructor operations.
110 No initialization or destruction overhead.
116 And the following disadvantages:
118 .Bl -enum -offset indent -compact
120 Should generally only be used as leaf mutexes.
122 Pool/pool dependency ordering cannot be guaranteed.
124 Possible L1 cache mastership contention between CPUs.
128 obtains a shared mutex from the specified pool.
129 This routine uses a simple rover to choose one of the shared mutexes managed
135 returns the shared mutex associated with the specified address.
136 This routine will create a hash out of the pointer passed into it
137 and will choose a shared mutex from the specified pool based on that hash.
138 The pointer does not need to point to anything real.
141 .Fn mtx_pool_lock_spin ,
142 .Fn mtx_pool_unlock ,
144 .Fn mtx_pool_unlock_spin
145 lock and unlock the shared mutex from the specified pool
146 associated with the specified address;
147 they are a combination of
151 .Xr mtx_lock_spin 9 ,
154 .Xr mtx_unlock_spin 9 ,
156 Since these routines must first find the mutex to operate on,
157 they are not as fast as directly using the mutex pointer returned by
158 a previous invocation of
164 allocates and initializes a new mutex pool of the
166 The pool size must be a power of two.
169 argument is passed to
171 to set the options for each mutex in the pool.
176 on each mutex in the specified pool,
177 deallocates the memory associated with the pool,
178 and assigns NULL to the pool pointer.
183 These routines first appeared in