Document mutex pool API enhancements that allow creation and use of

multiple mutex pools.

1 files changed, 65 insertions, 18 deletions

diff --git a/share/man/man9/mtx_pool.9 b/share/man/man9/mtx_pool.9
index 923d9f3..2de487e 100644
--- a/share/man/man9/mtx_pool.9
+++ b/share/man/man9/mtx_pool.9
@@ -35,30 +35,54 @@
 .Nm mtx_pool_alloc ,
 .Nm mtx_pool_find ,
 .Nm mtx_pool_lock ,
-.Nm mtx_pool_unlock
+.Nm mtx_pool_lock_spin ,
+.Nm mtx_pool_unlock ,
+.Nm mtx_pool_unlock_spin ,
+.Nm mtx_pool_create ,
+.Nm mtx_pool_destroy
 .Nd "mutex pool routines"
 .Sh SYNOPSIS
 .In sys/param.h
 .In sys/lock.h
 .In sys/mutex.h
 .Ft "struct mtx *"
-.Fn mtx_pool_alloc "void"
+.Fn mtx_pool_alloc "struct mtx_pool *pool"
 .Ft "struct mtx *"
-.Fn mtx_pool_find "void *ptr"
+.Fn mtx_pool_find "struct mtx_pool *pool" "void *ptr"
 .Ft void
-.Fn mtx_pool_lock "void *ptr"
+.Fn mtx_pool_lock "struct mtx_pool *pool" "void *ptr"
 .Ft void
-.Fn mtx_pool_unlock "void *ptr"
+.Fn mtx_pool_lock_spin "struct mtx_pool *pool" "void *ptr"
+.Ft void
+.Fn mtx_pool_unlock "struct mtx_pool *pool" "void *ptr"
+.Ft void
+.Fn mtx_pool_unlock_spin "struct mtx_pool *pool" "void *ptr"
+.Ft "struct mtx_pool *"
+.Fn mtx_pool_create "const char *mtx_name" "int pool_size" "int opts"
+.Ft "void"
+.Fn mtx_pool_destroy "struct mtx_pool **poolp"
 .Sh DESCRIPTION
 Mutex pools are designed to be used as short term leaf mutexes;
 i.e., the last mutex one might acquire before calling
 .Xr msleep 9 .
 They operate using a shared pool of mutexes.
-A mutex is chosen from the pool based on the supplied pointer,
-which may or may not point to anything valid.
+A mutex may be chosen from the pool based on a supplied pointer,
+which may or may not point to anything valid,
+or the caller may allocate an arbitrary shared mutex from the pool
+and save the returned mutex pointer for later use.
 .Pp
-The shared mutexes managed by the pool module are standard, non-recursive,
+The shared mutexes in the
+.Va mtxpool_sleep
+mutex pool,
+which is created by default,
+are standard, non-recursive,
 blockable mutexes, and should only be used in appropriate situations.
+The mutexes in the
+.Va mtxpool_lockbuilder
+mutex pool are similar except that are initialized with the MTX_NOWITNESS
+flag so that they may be used to build higher-level locks.
+Other mutex pools may be created that contain mutexes with different
+properties, such as spin mutexes.
 .Pp
 The caller can lock and unlock mutexes returned by the pool routines, but
 since the mutexes are shared, the caller should not attempt to destroy them
@@ -101,7 +125,7 @@ Possible L1 cache mastership contention between CPUs.
 .El
 .Pp
 .Fn mtx_pool_alloc
-obtains a shared mutex from the pool.
+obtains a shared mutex from the specified pool.
 This routine uses a simple rover to choose one of the shared mutexes managed
 by the
 .Nm
@@ -110,25 +134,48 @@ subsystem.
 .Fn mtx_pool_find
 returns the shared mutex associated with the specified address.
 This routine will create a hash out of the pointer passed into it
-and will choose a shared mutex based on that hash.
+and will choose a shared mutex from the specified pool based on that hash.
 The pointer does not need to point to anything real.
 .Pp
-.Fn mtx_pool_lock
+.Fn mtx_pool_lock ,
+.Fn mtx_pool_lock_spin ,
+.Fn mtx_pool_unlock ,
 and
-.Fn mtx_pool_unlock
-lock and unlock the shared mutex associated with the specified address,
-respectively;
+.Fn mtx_pool_unlock_spin
+lock and unlock the shared mutex from the specified pool
+associated with the specified address;
 they are a combination of
 .Fn mtx_pool_find
 and
-.Xr mtx_lock 9
-and
+.Xr mtx_lock 9 ,
+.Xr mtx_lock_spin 9 ,
 .Xr mtx_unlock 9 ,
+and
+.Xr mtx_unlock_spin 9 ,
 respectively.
 Since these routines must first find the mutex to operate on,
-they are not as fast as directly using the pointer (mutex) returned by
+they are not as fast as directly using the mutex pointer returned by
 a previous invocation of
-.Fn mtx_pool_find .
+.Fn mtx_pool_find
+or
+.Fn mtx_pool_alloc .
+.Pp
+.Fn mtx_pool_create
+allocates and initializes a new mutex pool of the
+specified size.
+The pool size must be a power of two.
+The
+.Fa opts
+argument is passed to
+.Xr mtx_init 9
+to set the options for each mutex in the pool.
+.Pp
+.Fn mtx_pool_destroy
+calls
+.Xr mtx_destroy 9
+on each mutex in the specified pool,
+deallocates the memory associated with the pool,
+and assigns NULL to the the pool pointer.
 .Pp
 .Sh SEE ALSO
 .Xr msleep 9 ,