home | help
MUTEX(9)		    Kernel Developer's Manual			MUTEX(9)

NAME
     mutex,	 mtx_init,	mtx_lock,     mtx_lock_spin,	 mtx_lock_flags,
     mtx_lock_spin_flags,    mtx_trylock,     mtx_trylock_flags,     mtx_unlock,
     mtx_unlock_spin,	mtx_unlock_flags,   mtx_unlock_spin_flags,  mtx_destroy,
     mtx_initialized, mtx_owned, mtx_recursed, mtx_assert, MTX_SYSINIT -- kernel
     synchronization primitives

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

     void
     mtx_init(struct mtx *mutex, const char *name, const char *type, int opts);

     void
     mtx_lock(struct mtx *mutex);

     void
     mtx_lock_spin(struct mtx *mutex);

     void
     mtx_lock_flags(struct mtx *mutex, int flags);

     void
     mtx_lock_spin_flags(struct mtx *mutex, int flags);

     int
     mtx_trylock(struct mtx *mutex);

     int
     mtx_trylock_flags(struct mtx *mutex, int flags);

     void
     mtx_unlock(struct mtx *mutex);

     void
     mtx_unlock_spin(struct mtx *mutex);

     void
     mtx_unlock_flags(struct mtx *mutex, int flags);

     void
     mtx_unlock_spin_flags(struct mtx *mutex, int flags);

     void
     mtx_destroy(struct mtx *mutex);

     int
     mtx_initialized(struct mtx *mutex);

     int
     mtx_owned(struct mtx *mutex);

     int
     mtx_recursed(struct mtx *mutex);

     void
     mtx_assert(struct mtx *mutex, int what);

     MTX_SYSINIT(name, struct mutex *mtx, const char *description, int opts);

DESCRIPTION
     Mutexes are the most basic and primary method of  process	synchronization.
     The major design considerations for mutexes are:

     1.   Acquiring and releasing uncontested mutexes should be as cheap as pos-
	  sible.

     2.   They	must  have the information and storage space to support priority
	  propagation.

     3.   A process must be able to recursively acquire a mutex,  provided  that
	  the mutex is initialized to support recursion.

     There  are currently two flavors of mutexes, those that context switch when
     they block and those that do not.

     By default, MTX_DEF mutexes will context switch when they are already held.
     As a machine dependent optimization they may spin for some amount	of  time
     before context switching.	It is important to remember that since a process
     may be preempted at any time, the possible context switch introduced by ac-
     quiring a mutex is guaranteed to not break anything that isn't already bro-
     ken.

     Mutexes  which  do  not  context switch are MTX_SPIN mutexes.  These should
     only be used to protect data shared with any devices that require	non-pre-
     emptive  interrupts,  and low level scheduling code.  In most/all architec-
     tures both acquiring and releasing of a uncontested spin mutex is more  ex-
     pensive  than  the same operation on a non spin mutex.  In order to protect
     an interrupt service routine from blocking against  itself  all  interrupts
     are blocked on a processor while holding a spin lock.  It is permissible to
     hold multiple spin mutexes.  In this case it is a required that they be re-
     leased in the opposite order to that which they were acquired.

     Once  a  spin  mutex  has	been acquired it is not permissible to acquire a
     blocking mutex.

     The storage needed to implement a mutex is provided by a  struct  mtx.   In
     general this should be treated as an opaque object and referenced only with
     the mutex primitives.

     The mtx_init() function must be used to initialize a mutex before it can be
     passed  to mtx_lock().  The name option is used to identify the lock in de-
     bugging output etc.  The type option is used by the witness code  to  clas-
     sify  a mutex when doing checks of lock ordering.	If type is NULL, name is
     used in its place.  The pointer passed in as name and type is saved  rather
     than  the	data it points to.  The data pointed to must remain stable until
     the mutex is destroyed.  The opts argument is used to set the type  of  mu-
     tex.   It	may  contain either MTX_DEF or MTX_SPIN but not both.  See below
     for additional initialization options.  It is not permissible to  pass  the
     same  mutex  to  mtx_init()  multiple  times  without  intervening calls to
     mtx_destroy().

     The mtx_lock() function acquires a MTX_DEF mutual exclusion lock on  behalf
     of  the currently running kernel thread.  If another kernel thread is hold-
     ing the mutex, the caller will be disconnected from the CPU until the mutex
     is available (i.e. it will sleep).

     The mtx_lock_spin() function acquires a MTX_SPIN mutual exclusion	lock  on
     behalf of the currently running kernel thread.  If another kernel thread is
     holding  the mutex, the caller will spin until the mutex becomes available.
     Interrupts are disabled during the spin and remain disabled  following  the
     acquiring of the lock.

     It  is  possible for the same thread to recursively acquire a mutex with no
     ill effects, provided that the MTX_RECURSE bit  was  passed  to  mtx_init()
     during the initialization of the mutex.

     The  mtx_lock_flags() and mtx_lock_spin_flags() functions acquire a MTX_DEF
     or MTX_SPIN lock, respectively, and also accept a flags argument.	In  both
     cases,  the  only	flag presently available for lock acquires is MTX_QUIET.
     If the MTX_QUIET bit is turned on in the flags argument, then  if	KTR_LOCK
     tracing is being done, it will be silenced during the lock acquire.

     The mtx_trylock() function is used to acquire exclusive access to those ob-
     jects  protected  by the mutex pointed to by mutex.  If the mutex cannot be
     immediately acquired mtx_trylock() will return 0, otherwise the mutex  will
     be acquired and a non-zero value will be returned.

     The mtx_trylock_flags() function has the same behavior as mtx_trylock() but
     should  be  used  when  the  caller  desires  to  pass  in  a  flags value.
     Presently, the only valid value in the mtx_trylock() case is MTX_QUIET, and
     its  effects  are	identical  to  those  described   for	mtx_lock()   and
     mtx_lock_spin() above.

     The  mtx_unlock()	function  releases a MTX_DEF mutual exclusion lock; if a
     higher priority thread is waiting for the mutex, the releasing thread  will
     be  disconnected  to  allow the higher priority thread to acquire the mutex
     and run unless the current thread is executing in a critical section.

     The mtx_unlock_spin() function releases a MTX_SPIN mutual	exclusion  lock;
     interrupt state prior to the acquiring of the lock is restored.

     The  mtx_unlock_flags() and mtx_unlock_spin_flags() functions behave in ex-
     actly the same way as do the standard mutex unlock  routines  above,  while
     also  allowing  a flags argument which may specify MTX_QUIET.  The behavior
     of MTX_QUIET is identical to its behavior in the mutex lock routines.

     The mtx_destroy() function is used to destroy mutex so the data  associated
     with  it  may  be	freed  or otherwise overwritten.  Any mutex which is de-
     stroyed must previously have been initialized with mtx_init().  It is  per-
     missible  to  have a single hold count on a mutex when it is destroyed.  It
     is not permissible to hold the mutex recursively, or have	another  process
     blocked on the mutex when it is destroyed.

     The  mtx_initialized() function returns non-zero if mutex has been initial-
     ized and zero otherwise.

     The mtx_owned() function returns non-zero	if  the  current  process  holds
     mutex.  If the current process does not hold mutex zero is returned.

     The  mtx_recursed()  function  returns  non-zero  if the mutex is recursed.
     This check should only be made if the running thread already owns mutex.

     The mtx_assert() function allows assertions to be made about mutex.  If the
     assertions are not true and the kernel is compiled with INVARIANTS then the
     kernel will panic.  Currently the following assertions are supported:

     MA_OWNED	     Assert that the current thread holds the mutex  pointed  to
		     by the first argument.

     MA_NOTOWNED     Assert  that  the	current  thread  does not hold the mutex
		     pointed to by the first argument.

     MA_RECURSED     Assert that the current thread has recursed  on  the  mutex
		     pointed  to  by the first argument.  This assertion is only
		     valid in conjunction with MA_OWNED.

     MA_NOTRECURSED  Assert that the current thread has not recursed on the  mu-
		     tex  pointed  to  by the first argument.  This assertion is
		     only valid in conjunction with MA_OWNED.

     The MTX_SYSINIT() macro is used to generate a  call  to  the  mtx_sysinit()
     routine  at  system startup in order to initialize a given mutex lock.  The
     parameters are the same as mtx_init()  but  with  an  additional  argument,
     name,  that  is  used  in	generating unique variable names for the related
     structures associated with the lock and the sysinit routine.

   The Default Mutex Type
     Most kernel code should use the default lock  type,  MTX_DEF;  the  default
     lock  type will allow the thread to be disconnected from the CPU if it can-
     not get the lock.	The machine dependent implementation may treat the  lock
     as  a short term spin lock under some circumstances.  However, it is always
     safe to use these forms of locks in an interrupt  thread  without	fear  of
     deadlock against an interrupted thread on the same CPU.

   The Spin Mutex Type
     A MTX_SPIN mutex will not relinquish the CPU when it cannot immediately get
     the  requested lock, but will loop, waiting for the mutex to be released by
     another CPU.  This could result in deadlock if  a	thread	interrupted  the
     thread  which  held  a  mutex and then tried to acquire the mutex; for this
     reason spin locks will disable all interrupts (on the local CPU only).

     Spin locks are fairly specialized locks that are intended to  be  held  for
     very short periods of time; their primary purpose is to protect portions of
     the code that implement default (i.e. sleep) locks.

   Initialization Options
     The  options  passed  in  the opts argument of mtx_init() specify the mutex
     type.  The possibilities are:

     MTX_DEF	    Default lock type; will always allow the current  thread  to
		    be	suspended to avoid deadlock conditions against interrupt
		    threads.  The machine dependent implementation of this  lock
		    type  may  spin  for  a  while before suspending the current
		    thread.  If this flag is specified,  clearly  MTX_SPIN  must
		    NOT be specified.

     MTX_SPIN	    Spin  lock	type; will never relinquish the CPU.  All inter-
		    rupts are disabled on the local CPU while any spin	lock  is
		    held.

     MTX_RECURSE    Recursion  option  bit; specifies that the initialized mutex
		    is allowed to recurse.  This bit must be present if the  mu-
		    tex is going to be permitted to recurse.

     MTX_QUIET	    Do not log any mutex operations for this lock.

     MTX_NOWITNESS  Instruct witness(4) to ignore this lock.

     MTX_DUPOK	    Witness  should not log messages about duplicate locks being
		    acquired.

   Lock and Unlock Flags
     The flags passed to the  mtx_lock_flags(),  mtx_lock_spin_flags(),  mtx_un-
     lock_flags(),  and mtx_unlock_spin_flags() functions provide some basic op-
     tions to the caller, and are often used only under special circumstances to
     modify lock or unlock behavior.  Standard locking and unlocking  should  be
     performed	with  the mtx_lock(), mtx_lock_spin(), mtx_unlock(), and mtx_un-
     lock_spin() functions.  Only if a flag is required should the corresponding
     flags-accepting routines be used.

     Options that modify mutex behavior:

     MTX_QUIET	This option is used to quiet logging messages during  individual
		mutex  operations.  This can be used to trim superfluous logging
		messages for debugging purposes.

   Giant
     If Giant must be acquired, it must be acquired prior to acquiring other mu-
     texes.  Put another way: it is impossible to acquire Giant  non-recursively
     while holding another mutex.  It is possible to acquire other mutexes while
     holding  Giant, and it is possible to acquire Giant recursively while hold-
     ing other mutexes.

   Sleeping
     Sleeping while holding a mutex (except for Giant) is almost never safe  and
     should  be  avoided.  There are numerous assertions which will fail if this
     is attempted.

   Functions Which Access Memory in Userspace
     No mutexes should be held (except for Giant) across functions which  access
     memory  in userspace, such as copyin(9), copyout(9), uiomove(9), fuword(9),
     etc.  No locks are needed when calling these functions.

SEE ALSO
     condvar(9), msleep(9), mtx_pool(9), sema(9), sx(9)

HISTORY
     These functions appeared in BSD/OS 4.1 and FreeBSD 5.0.

FreeBSD 5.0			February 12, 2001			MUTEX(9)

home | help