Date: Tue, 26 Mar 2002 19:00:26 -0500 (EST) From: garrett rooney <rooneg@electricjellyfish.net> To: FreeBSD-gnats-submit@FreeBSD.org Cc: dillon@FreeBSD.org Subject: docs/36350: [PATCH] new mtx_pool.9 man page Message-ID: <200203270000.g2R00QO85847@neroon.user.acm.rpi.edu>
next in thread | raw e-mail | index | archive | help
>Number: 36350 >Category: docs >Synopsis: [PATCH] new mtx_pool.9 man page >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Tue Mar 26 16:10:02 PST 2002 >Closed-Date: >Last-Modified: >Originator: garrett rooney >Release: FreeBSD 5.0-CURRENT i386 >Organization: >Environment: System: FreeBSD snowcrash.electricjellyfish.net 5.0-CURRENT FreeBSD 5.0-CURRENT #0: Sun Mar 24 23:41:30 EST 2002 rooneg@snowcrash:/usr/obj/usr/src/sys/SNOWCRASH i386 >Description: the mtx_pool API lacks a man page. >How-To-Repeat: man mtx_pool ;-) >Fix: apply the following patch in src/share/man/man9. --- /dev/null Tue Mar 26 18:44:00 2002 +++ mtx_pool.9 Tue Mar 26 18:53:49 2002 @@ -0,0 +1,134 @@ +.\" +.\" Copyright (C) 2002 Garrett Rooney <rooneg@electricjellyfish.net>. All +.\" rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +.\" DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 25, 2002 +.Dt MTX_POOL 9 +.Os +.Sh NAME +.Nm mtx_pool , +.Nm mtx_pool_alloc , +.Nm mtx_pool_find , +.Nm mtx_lock_lock , +.Nm mtx_lock_unlock +.Nd mutex pool routines +.Sh SYNOPSIS +.In sys/mutex.h +.Ft struct mtx * +.Fn mtx_pool_alloc "void" +.Ft struct mtx * +.Fn mtx_pool_find "void *ptr" +.Ft void +.Fn mtx_pool_lock "void *ptr" +.Ft void +.Fn mtx_pool_unlock "void *ptr" +.Sh DESCRIPTION +Mutex pools are designed to be used as short term leaf mutexes, e.g. the +last mutex you might acquire other than calling +.Fn msleep . +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 be valid). +.Pp +The shared mutex managed by the pool module are standard, non-recursive, +blockable mutexes, and should only be used in appropriate situations. +.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 +or modify their characteristics. +While pool mutexes are normally 'leaf' mutexes, meaning that you cannot +depend on any ordering guarantees after obtaining one, you can still obtain +other mutexes under carefully controlled circumstances. +Specifically, if you have a private mutex (that you allocate and +.Fn mtx_init +yourself), and you carefully manage the ordering issues, you can obtain your +private mutex after obtaining the pool mutex. +In these cases the private mute winds up being the true 'leaf' mutex. +.Pp +Mutex pools have the following advantages: +.Bl -enum +.It +No structural overhead. +Mutexes can be associated with structures without adding bloat to the structures. +.It +Mutexes can be obtained for invalid pointers, which is useful when one uses +mutexes to interlock destructor operations. +.It +No initialization/destruction overhead. +.It +Can be used with msleep. +.El +.Pp +And the following disadvantages: +.Bl -enum +.It +Should generally only be used as leaf mutexes. +.It +Pool/pool dependency ordering cannot be depended on. +.It +Possible L1 cache mastership contention between CPUs. +.El +.Pp +.Fn mtx_pool_alloc +obtains a shared mutex from the pool. +This routine uses a simple rover to choose one of the shared mutexes managed +by the module. +.Pp +.Fn mtx_pool_find +returns the shared mutex associated with the specified address. +This routine will create a hash out of the arbitrary pointer passed into it +and will choose a shared mutex based on the hash. +The pointer need not point to anything real. +.Pp +.Fn mtx_pool_lock +locks the shared mutex associated with the specified address. +This routine provides an easy-to-use combination of +.Fn mtx_pool_find +and +.Fn mtx_pool_lock . +Note that because it must hash the pointer passed to it, this will not be +as fast as storing the pointer returned by a previous +.Fn mtx_pool_find . +.Pp +.Fn mtx_pool_unlock +unlocks the shared mutex associated with the specified address. +This routine provides an easy-to-use combination of +.Fn mtx_pool_find +and +.Fn mtx_pool_unlock . +Note that because it must hash the pointer passed to it, this will not be +as fast as storing the pointer returned by a previous +.Fn mtx_pool_find . +.Pp +.Sh SEE ALSO +.Xr mutex 9 , +.Xr msleep 9 +.Sh HISTORY +These +functions appeared in +.Fx 5.0 . Index: Makefile =================================================================== RCS file: /home/ncvs/src/share/man/man9/Makefile,v retrieving revision 1.154 diff -u -r1.154 Makefile --- Makefile 2002/03/13 01:42:33 1.154 +++ Makefile 2002/03/27 00:00:14 @@ -49,7 +49,7 @@ lock.9 \ make_dev.9 malloc.9 mbchain.9 mbuf.9 mdchain.9 \ mi_switch.9 microseq.9 microtime.9 microuptime.9 \ - module.9 mutex.9 \ + module.9 mtx_pool.9 mutex.9 \ namei.9 \ panic.9 pbuf.9 pfil.9 pfind.9 pgfind.9 \ physio.9 posix4.9 printf.9 pseudofs.9 psignal.9 \ @@ -309,6 +309,9 @@ MLINKS+=microtime.9 getnanotime.9 MLINKS+=microuptime.9 getmicrouptime.9 microuptime.9 nanouptime.9 MLINKS+=microuptime.9 getnanouptime.9 + +MLINKS+=mtx_pool.9 mtx_pool_alloc.9 mtx_pool.9 mtx_pool_find.9 +MLINKS+=mtx_pool.9 mtx_pool_lock.9 mtx_pool.9 mtx_pool_unlock.9 MLINKS+=mutex.9 mtx_init.9 MLINKS+=mutex.9 mtx_lock.9 mutex.9 mtx_lock_flags.9 Index: condvar.9 =================================================================== RCS file: /home/ncvs/src/share/man/man9/condvar.9,v retrieving revision 1.7 diff -u -r1.7 condvar.9 --- condvar.9 2001/12/26 23:14:04 1.7 +++ condvar.9 2002/03/27 00:00:15 @@ -195,6 +195,7 @@ .El .Sh SEE ALSO .Xr msleep 9 , +.Xr mtx_pool 9 , .Xr mutex 9 , .Xr sema 9 , .Xr sx 9 Index: mutex.9 =================================================================== RCS file: /home/ncvs/src/share/man/man9/mutex.9,v retrieving revision 1.23 diff -u -r1.23 mutex.9 --- mutex.9 2002/01/09 11:43:48 1.23 +++ mutex.9 2002/03/27 00:00:17 @@ -465,6 +465,7 @@ .Sh SEE ALSO .Xr condvar 9 , .Xr msleep 9 , +.Xr mtx_pool 9 , .Xr sema 9 , .Xr sx 9 .Sh HISTORY Index: sema.9 =================================================================== RCS file: /home/ncvs/src/share/man/man9/sema.9,v retrieving revision 1.5 diff -u -r1.5 sema.9 --- sema.9 2001/12/26 23:14:04 1.5 +++ sema.9 2002/03/27 00:00:17 @@ -107,5 +107,6 @@ will be returned to indicate success. .Sh SEE ALSO .Xr condvar 9 , +.Xr mtx_pool 9 , .Xr mutex 9 , .Xr sx 9 Index: sx.9 =================================================================== RCS file: /home/ncvs/src/share/man/man9/sx.9,v retrieving revision 1.15 diff -u -r1.15 sx.9 --- sx.9 2001/11/21 11:47:55 1.15 +++ sx.9 2002/03/27 00:00:17 @@ -146,6 +146,7 @@ attempting to do so will result in deadlock. .Sh SEE ALSO .Xr condvar 9 , +.Xr mtx_pool 9 , .Xr mutex 9 , .Xr sema 9 .Sh BUGS >Release-Note: >Audit-Trail: >Unformatted: To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200203270000.g2R00QO85847>