/share/man/man9/mtx_pool.9

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