Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MTX_POOL(9)		 BSD Kernel Developer's	Manual		   MTX_POOL(9)

     mtx_pool, mtx_pool_alloc, mtx_pool_find, mtx_pool_lock, mtx_pool_unlock
     --	mutex pool routines

     #include <sys/param.h>
     #include <sys/lock.h>
     #include <sys/mutex.h>

     struct mtx	*

     struct mtx	*
     mtx_pool_find(void	*ptr);

     mtx_pool_lock(void	*ptr);

     mtx_pool_unlock(void *ptr);

     Mutex pools are designed to be used as short term leaf mutexes; i.e., the
     last mutex	one might acquire before calling msleep(9).  They operate us-
     ing 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.

     The shared	mutexes	managed	by the pool module are standard, non-recur-
     sive, blockable mutexes, and should only be used in appropriate situa-

     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	one cannot depend on any ordering guarantees
     after obtaining one), one can still obtain	other mutexes under carefully
     controlled	circumstances.	Specifically, if one has a private mutex (one
     that was allocated	and initialized	by the caller),	one can	obtain it af-
     ter obtaining a pool mutex	if ordering issues are carefully accounted
     for.  In these cases the private mutex winds up being the true leaf mu-

     Pool mutexes have the following advantages:

	   1.	No structural overhead;	i.e., they can be associated with a
		structure without adding bloat to it.
	   2.	Mutexes	can be obtained	for invalid pointers, which is useful
		when one uses mutexes to interlock destructor operations.
	   3.	No initialization or destruction overhead.
	   4.	Can be used with msleep(9).

     And the following disadvantages:

	   1.	Should generally only be used as leaf mutexes.
	   2.	Pool/pool dependency ordering cannot be	guaranteed.
	   3.	Possible L1 cache mastership contention	between	CPUs.

     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
     mtx_pool subsystem.

     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.  The	pointer	does
     not need to point to anything real.

     mtx_pool_lock() and mtx_pool_unlock() lock	and unlock the shared mutex
     associated	with the specified address, respectively; they are a combina-
     tion of mtx_pool_find() and mtx_lock(9) and mtx_unlock(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 a previous
     invocation	of mtx_pool_find().

     msleep(9),	mutex(9)

     These routines first appeared in FreeBSD 5.0.

BSD				March 25, 2002				   BSD


Want to link to this manual page? Use this URL:

home | help