From rooneg@neroon.user.acm.rpi.edu  Tue Mar 26 16:05:45 2002
Return-Path: <rooneg@neroon.user.acm.rpi.edu>
Received: from neroon.user.acm.rpi.edu (neroon.user.acm.rpi.edu [128.213.5.66])
	by hub.freebsd.org (Postfix) with ESMTP
	id 1018737B404; Tue, 26 Mar 2002 16:05:44 -0800 (PST)
Received: (from rooneg@localhost)
	by neroon.user.acm.rpi.edu (8.11.6/8.11.6) id g2R00QO85847;
	Tue, 26 Mar 2002 19:00:26 -0500 (EST)
	(envelope-from rooneg)
Message-Id: <200203270000.g2R00QO85847@neroon.user.acm.rpi.edu>
Date: Tue, 26 Mar 2002 19:00:26 -0500 (EST)
From: garrett rooney <rooneg@electricjellyfish.net>
Reply-To: garrett rooney <rooneg@electricjellyfish.net>
To: FreeBSD-gnats-submit@freebsd.org
Cc: dillon@freebsd.org
Subject: [PATCH] new mtx_pool.9 man page
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         36350
>Category:       docs
>Synopsis:       [PATCH] new mtx_pool.9 man page
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Mar 26 16:10:02 PST 2002
>Closed-Date:    Thu Mar 28 04:58:09 PST 2002
>Last-Modified:  Thu Mar 28 04:58:09 PST 2002
>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:

From: Dima Dorfman <dima@trit.org>
To: dillon@FreeBSD.org
Cc: FreeBSD-gnats-submit@FreeBSD.org,
	garrett rooney <rooneg@electricjellyfish.net>
Subject: Re: docs/36350: [PATCH] new mtx_pool.9 man page 
Date: Wed, 27 Mar 2002 02:22:57 +0000

 garrett rooney <rooneg@electricjellyfish.net> wrote:
 > >Description:
 > 	the mtx_pool API lacks a man page.
 
 Matt,
 
 If you could review the manual page submitted here for technical
 validity, I'll fix up the markup and English bogons and commit it.
 
 Thanks.

From: Garrett Rooney <rooneg@electricjellyfish.net>
To: Dima Dorfman <dima@trit.org>
Cc: dillon@FreeBSD.org, FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/36350: [PATCH] new mtx_pool.9 man page
Date: Tue, 26 Mar 2002 21:24:45 -0500

 On Wed, Mar 27, 2002 at 02:22:57AM +0000, Dima Dorfman wrote:
 > garrett rooney <rooneg@electricjellyfish.net> wrote:
 > > >Description:
 > > 	the mtx_pool API lacks a man page.
 > 
 > Matt,
 > 
 > If you could review the manual page submitted here for technical
 > validity, I'll fix up the markup and English bogons and commit it.
 
 actually, i already ran an earlier version past matt, and this has his
 suggestions added in.  it would be good if he could give it a once
 over though, in case i messed something up.
 
 -garrett 
 
 -- 
 garrett rooney                     Unix was not designed to stop you from 
 rooneg@electricjellyfish.net       doing stupid things, because that would  
 http://electricjellyfish.net/      stop you from doing clever things.

From: Matthew Dillon <dillon@apollo.backplane.com>
To: Garrett Rooney <rooneg@electricjellyfish.net>
Cc: Dima Dorfman <dima@trit.org>, FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/36350: [PATCH] new mtx_pool.9 man page
Date: Tue, 26 Mar 2002 19:46:51 -0800 (PST)

 :
 :On Wed, Mar 27, 2002 at 02:22:57AM +0000, Dima Dorfman wrote:
 :> garrett rooney <rooneg@electricjellyfish.net> wrote:
 :> > >Description:
 :> > 	the mtx_pool API lacks a man page.
 :> 
 :> Matt,
 :> 
 :> If you could review the manual page submitted here for technical
 :> validity, I'll fix up the markup and English bogons and commit it.
 :
 :actually, i already ran an earlier version past matt, and this has his
 :suggestions added in.  it would be good if he could give it a once
 :over though, in case i messed something up.
 :
 :-garrett 
 :
 :-- 
 :garrett rooney                     Unix was not designed to stop you from 
 
     Hi guys!  Yah, it already contains the suggestions I made.  Dima,
     please go ahead and fix the markup & english bogons you see and
     then go ahead and commit it!  Thanks!
 
     I noticed one spelling error in the PR:
 
 In these cases the private mute winds 
 
     to
 
 In these cases the private mutex winds 
 
 					-Matt
 					Matthew Dillon 
 					<dillon@backplane.com>
 

From: Garrett Rooney <rooneg@electricjellyfish.net>
To: Matthew Dillon <dillon@apollo.backplane.com>
Cc: Dima Dorfman <dima@trit.org>, FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/36350: [PATCH] new mtx_pool.9 man page
Date: Tue, 26 Mar 2002 22:55:18 -0500

 On Tue, Mar 26, 2002 at 07:46:51PM -0800, Matthew Dillon wrote:
 
 >     Hi guys!  Yah, it already contains the suggestions I made.  Dima,
 >     please go ahead and fix the markup & english bogons you see and
 >     then go ahead and commit it!  Thanks!
 > 
 >     I noticed one spelling error in the PR:
 > 
 > In these cases the private mute winds 
 > 
 >     to
 > 
 > In these cases the private mutex winds 
 
 gah!  that'll teach me to trust spell checkers...  i can't believe i
 didn't see that one...
 
 btw, Dima, if you could just let me know what kind of markup errors
 you find, that would be great.  i'm fairly new at writing man pages, 
 and any tips on things to avoid in the future would be much
 appreciated.
 
 thanks,
 
 -garrett
 
 -- 
 garrett rooney                     Unix was not designed to stop you from 
 rooneg@electricjellyfish.net       doing stupid things, because that would  
 http://electricjellyfish.net/      stop you from doing clever things.
State-Changed-From-To: open->closed 
State-Changed-By: dd 
State-Changed-When: Thu Mar 28 04:57:57 PST 2002 
State-Changed-Why:  
Committed, thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=36350 
>Unformatted:
