.\"

.\" 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 .

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

.Xr mtx_pool 9 ,

.Xr mtx_pool 9 ,

.Xr mtx_pool 9 ,

.Xr mtx_pool 9 ,