mutex_init man page on NetBSD

Man page or keyword search:  
man Server   9087 pages
apropos Keyword Search (all sections)
Output format
NetBSD logo
[printable version]

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 processes) 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 synchro‐
     nization between interrupt handlers and LWPs.

OPTIONS
     options DIAGNOSTIC

	   Kernels compiled with the DIAGNOSTIC option perform basic sanity
	   checks on mutex operations.

     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 attempt‐
		 ing 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 han‐
		 dlers.

		 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 con‐
	   sistent 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 substan‐
	   tially 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 substan‐
	   tially 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 con‐
	   vention 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
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server NetBSD

List of man pages available for NetBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net