👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

NetBSD 6.1.5 - man page for mutex_init (netbsd section 9)

MUTEX(9)			  BSD Kernel Developer's Manual 			 MUTEX(9)

NAME
     mutex, mutex_init, mutex_destroy, mutex_enter, mutex_exit, mutex_owned, mutex_spin_enter,
     mutex_spin_exit, mutex_tryenter -- mutual exclusion primitives

SYNOPSIS
     #include <sys/mutex.h>

     void
     mutex_init(kmutex_t *mtx, kmutex_type_t type, int ipl);

     void
     mutex_destroy(kmutex_t *mtx);

     void
     mutex_enter(kmutex_t *mtx);

     void
     mutex_exit(kmutex_t *mtx);

     int
     mutex_owned(kmutex_t *mtx);

     void
     mutex_spin_enter(kmutex_t *mtx);

     void
     mutex_spin_exit(kmutex_t *mtx);

     int
     mutex_tryenter(kmutex_t *mtx);

     options DIAGNOSTIC
     options LOCKDEBUG

DESCRIPTION
     Mutexes are used in the kernel to implement mutual exclusion among LWPs (lightweight pro-
     cesses) and interrupt handlers.

     The kmutex_t type provides storage for the mutex object.  This should be treated as an
     opaque object and not examined directly by consumers.

     Mutexes replace the spl(9) system traditionally used to provide synchronization between
     interrupt handlers and LWPs.

OPTIONS
     options DIAGNOSTIC

	   Kernels compiled with the DIAGNOSTIC option perform basic sanity checks on mutex oper-
	   ations.

     options LOCKDEBUG

	   Kernels compiled with the LOCKDEBUG option perform potentially CPU intensive sanity
	   checks on mutex operations.

FUNCTIONS
     mutex_init(mtx, type, ipl)

	   Dynamically initialize a mutex for use.

	   No other operations can be performed on a mutex until it has been initialized.  Once
	   initialized, all types of mutex are manipulated using the same interface.  Note that
	   mutex_init() may block in order to allocate memory.

	   The type argument must be given as MUTEX_DEFAULT.  Other constants are defined but are
	   for low-level system use and are not an endorsed, stable part of the interface.

	   The type of mutex returned depends on the ipl argument:

	   IPL_NONE, or one of the IPL_SOFT* constants

		 An adaptive mutex will be returned.  Adaptive mutexes provide mutual exclusion
		 between LWPs, and between LWPs and soft interrupt handlers.

		 Adaptive mutexes cannot be acquired from a hardware interrupt handler.  An LWP
		 may either sleep or busy-wait when attempting to acquire an adaptive mutex that
		 is already held.

	   IPL_VM, IPL_SCHED, IPL_HIGH

		 A spin mutex will be returned.  Spin mutexes provide mutual exclusion between
		 LWPs, and between LWPs and interrupt handlers.

		 The ipl argument is used to pass a system interrupt priority level (IPL) that
		 will block all interrupt handlers that may try to acquire the mutex.

		 LWPs that own spin mutexes may not sleep, and therefore must not try to acquire
		 adaptive mutexes or other sleep locks.

		 A processor will always busy-wait when attempting to acquire a spin mutex that
		 is already held.

	   See spl(9) for further information on interrupt priority levels (IPLs).

     mutex_destroy(mtx)

	   Release resources used by a mutex.  The mutex may not be used after it has been
	   destroyed.  mutex_destroy() may block in order to free memory.

     mutex_enter(mtx)

	   Acquire a mutex.  If the mutex is already held, the caller will block and not return
	   until the mutex is acquired.

	   Mutexes and other types of locks must always be acquired in a consistent order with
	   respect to each other.  Otherwise, the potential for system deadlock exists.

	   Adaptive mutexes and other types of lock that can sleep may not be acquired while a
	   spin mutex is held by the caller.

	   When acquiring a spin mutex, the IPL of the current CPU will be raised to the level
	   set in mutex_init() if it is not already equal or higher.

     mutex_exit(mtx)

	   Release a mutex.  The mutex must have been previously acquired by the caller.  Mutexes
	   may be released out of order as needed.

     mutex_owned(mtx)

	   For adaptive mutexes, return non-zero if the current LWP holds the mutex.  For spin
	   mutexes, return non-zero if the mutex is held, potentially by the current processor.
	   Otherwise, return zero.

	   mutex_owned() is provided for making diagnostic checks to verify that a lock is held.
	   For example:

		   KASSERT(mutex_owned(&driver_lock));

	   It should not be used to make locking decisions at run time, or to verify that a lock
	   is not held.

     mutex_spin_enter(mtx)

	   Equivalent to mutex_enter(), but may only be used when it is known that mtx is a spin
	   mutex.  On some architectures, this can substantially reduce the cost of acquring a
	   spin mutex.

     mutex_spin_exit(mtx)

	   Equivalent to mutex_exit(), but may only be used when it is known that mtx is a spin
	   mutex.  On some architectures, this can substantially reduce the cost of releasing a
	   spin mutex.

     mutex_tryenter(mtx)

	   Try to acquire a mutex, but do not block if the mutex is already held.  Returns non-
	   zero if the mutex was acquired, or zero if the mutex was already held.

	   mutex_tryenter() can be used as an optimization when acquiring locks in the wrong
	   order.  For example, in a setting where the convention is that first_lock must be
	   acquired before second_lock, the following can be used to optimistically lock in
	   reverse order:

		   /* We hold second_lock, but not first_lock. */
		   KASSERT(mutex_owned(&second_lock));

		   if (!mutex_tryenter(&first_lock)) {
			   /* Failed to get it - lock in the correct order. */
			   mutex_exit(&second_lock);
			   mutex_enter(&first_lock);
			   mutex_enter(&second_lock);

			   /*
			    * We may need to recheck any conditions the code
			    * path depends on, as we released second_lock
			    * briefly.
			    */
		   }

CODE REFERENCES
     The core of the mutex implementation is in sys/kern/kern_mutex.c.

     The header file sys/sys/mutex.h describes the public interface, and interfaces that machine-
     dependent code must provide to support mutexes.

SEE ALSO
     atomic_ops(3), membar_ops(3), lockstat(8), condvar(9), kpreempt(9), rwlock(9), spl(9)

     Jim Mauro and Richard McDougall, Solaris Internals: Core Kernel Architecture, Prentice Hall,
     2001, ISBN 0-13-022496-0.

HISTORY
     The mutex primitives first appeared in NetBSD 5.0.

BSD					September 14, 2010				      BSD


All times are GMT -4. The time now is 05:57 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password