Attachment 20625 Details for Bug 36350 – file.diff

[patch] file.diff

file.diff (text/plain), 7.26 KB, created by rooneg on 2002-03-27 00:10:02 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: rooneg

Created: 2002-03-27 00:10:02 UTC

Size: 7.26 KB

patch

obsolete

>--- /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

Actions: View | Diff

Attachments on bug 36350: 20625