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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
RMLOCK(9)	       FreeBSD Kernel Developer's Manual	     RMLOCK(9)

NAME
     rmlock, rm_init, rm_init_flags, rm_destroy, rm_rlock, rm_try_rlock,
     rm_wlock, rm_runlock, rm_wunlock, rm_wowned, rm_sleep, rm_assert,
     RM_SYSINIT	-- kernel reader/writer	lock optimized for read-mostly access
     patterns

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

     void
     rm_init(struct rmlock *rm,	const char *name);

     void
     rm_init_flags(struct rmlock *rm, const char *name,	int opts);

     void
     rm_destroy(struct rmlock *rm);

     void
     rm_rlock(struct rmlock *rm, struct	rm_priotracker*	tracker);

     int
     rm_try_rlock(struct rmlock	*rm, struct rm_priotracker* tracker);

     void
     rm_wlock(struct rmlock *rm);

     void
     rm_runlock(struct rmlock *rm, struct rm_priotracker* tracker);

     void
     rm_wunlock(struct rmlock *rm);

     int
     rm_wowned(struct rmlock *rm);

     int
     rm_sleep(void *wchan, struct rmlock *rm, int priority, const char *wmesg,
	 int timo);

     options INVARIANTS
     options INVARIANT_SUPPORT

     void
     rm_assert(struct rmlock *rm, int what);

     #include <sys/kernel.h>

     RM_SYSINIT(name, struct rmlock *rm, const char *desc, int opts);

DESCRIPTION
     Read-mostly locks allow shared access to protected	data by	multiple
     threads, or exclusive access by a single thread.  The threads with	shared
     access are	known as readers since they only read the protected data.  A
     thread with exclusive access is known as a	writer since it	can modify
     protected data.

     Read-mostly locks are designed to be efficient for	locks almost exclu-
     sively used as reader locks and as	such should be used for	protecting
     data that rarely changes.	Acquiring an exclusive lock after the lock has
     been locked for shared access is an expensive operation.

     Normal read-mostly	locks are similar to rwlock(9) locks and follow	the
     same lock ordering	rules as rwlock(9) locks.  Read-mostly locks have full
     priority propagation like mutexes.	 Unlike	rwlock(9), read-mostly locks
     propagate priority	to both	readers	and writers.  This is implemented via
     the rm_priotracker	structure argument supplied to rm_rlock() and
     rm_runlock().  Readers can	recurse	if the lock is initialized with	the
     RM_RECURSE	option;	however, writers are never allowed to recurse.

     Sleepable read-mostly locks are created by	passing	RM_SLEEPABLE to
     rm_init_flags().  Unlike normal read-mostly locks,	sleepable read-mostly
     locks follow the same lock	ordering rules as sx(9)	locks.	Sleepable
     read-mostly locks do not propagate	priority to writers, but they do prop-
     agate priority to readers.	 Writers are permitted to sleep	while holding
     a read-mostly lock, but readers are not.  Unlike other sleepable locks
     such as sx(9) locks, readers must use try operations on other sleepable
     locks to avoid sleeping.

   Macros and Functions
     rm_init(struct rmlock *rm,	const char *name)
	     Initialize	the read-mostly	lock rm.  The name description is used
	     solely for	debugging purposes.  This function must	be called
	     before any	other operations on the	lock.

     rm_init_flags(struct rmlock *rm, const char *name,	int opts)
	     Similar to	rm_init(), initialize the read-mostly lock rm with a
	     set of optional flags.  The opts arguments	contains one or	more
	     of	the following flags:

	     RM_NOWITNESS  Instruct witness(4) to ignore this lock.

	     RM_RECURSE	   Allow threads to recursively	acquire	shared locks
			   for rm.

	     RM_SLEEPABLE  Create a sleepable read-mostly lock.

     rm_rlock(struct rmlock *rm, struct	rm_priotracker*	tracker)
	     Lock rm as	a reader using tracker to track	read owners of a lock
	     for priority propagation.	This data structure is only used
	     internally	by rmlock and must persist until rm_runlock() has been
	     called.  This data	structure can be allocated on the stack	since
	     readers cannot sleep.  If any thread holds	this lock exclusively,
	     the current thread	blocks,	and its	priority is propagated to the
	     exclusive holder.	If the lock was	initialized with the
	     RM_RECURSE	option the rm_rlock() function can be called when the
	     current thread has	already	acquired reader	access on rm.

     rm_try_rlock(struct rmlock	*rm, struct rm_priotracker* tracker)
	     Try to lock rm as a reader.  rm_try_rlock() will return 0 if the
	     lock cannot be acquired immediately; otherwise, the lock will be
	     acquired and a non-zero value will	be returned.  Note that
	     rm_try_rlock() may	fail even while	the lock is not	currently held
	     by	a writer.  If the lock was initialized with the	RM_RECURSE
	     option, rm_try_rlock() will succeed if the	current	thread has
	     already acquired reader access.

     rm_wlock(struct rmlock *rm)
	     Lock rm as	a writer.  If there are	any shared owners of the lock,
	     the current thread	blocks.	 The rm_wlock()	function cannot	be
	     called recursively.

     rm_runlock(struct rmlock *rm, struct rm_priotracker* tracker)
	     This function releases a shared lock previously acquired by
	     rm_rlock().  The tracker argument must match the tracker argument
	     used for acquiring	the shared lock

     rm_wunlock(struct rmlock *rm)
	     This function releases an exclusive lock previously acquired by
	     rm_wlock().

     rm_destroy(struct rmlock *rm)
	     This functions destroys a lock previously initialized with
	     rm_init().	 The rm	lock must be unlocked.

     rm_wowned(struct rmlock *rm)
	     This function returns a non-zero value if the current thread owns
	     an	exclusive lock on rm.

     rm_sleep(void *wchan, struct rmlock *rm, int priority, const char *wmesg,
	     int timo)
	     This function atomically releases rm while	waiting	for an event.
	     The rm lock must be exclusively locked.  For more details on the
	     parameters	to this	function, see sleep(9).

     rm_assert(struct rmlock *rm, int what)
	     This function asserts that	the rm lock is in the state specified
	     by	what.  If the assertions are not true and the kernel is	com-
	     piled with	options	INVARIANTS and options INVARIANT_SUPPORT, the
	     kernel will panic.	 Currently the following base assertions are
	     supported:

	     RA_LOCKED	  Assert that current thread holds either a shared or
			  exclusive lock of rm.

	     RA_RLOCKED	  Assert that current thread holds a shared lock of
			  rm.

	     RA_WLOCKED	  Assert that current thread holds an exclusive	lock
			  of rm.

	     RA_UNLOCKED  Assert that current thread holds neither a shared
			  nor exclusive	lock of	rm.

	     In	addition, one of the following optional	flags may be specified
	     with RA_LOCKED, RA_RLOCKED, or RA_WLOCKED:

	     RA_RECURSED     Assert that the current thread holds a recursive
			     lock of rm.

	     RA_NOTRECURSED  Assert that the current thread does not hold a
			     recursive lock of rm.

SEE ALSO
     locking(9), mutex(9), panic(9), rwlock(9),	sleep(9), sema(9), sx(9)

HISTORY
     These functions appeared in FreeBSD 7.0.

AUTHORS
     The rmlock	facility was written by	Stephan	Uphoff.	 This manual page was
     written by	Gleb Smirnoff for rwlock and modified to reflect rmlock	by
     Stephan Uphoff.

BUGS
     The rmlock	implementation is currently not	optimized for single processor
     systems.

     rm_try_rlock() can	fail transiently even when there is no writer, while
     another reader updates the	state on the local CPU.

     The rmlock	implementation uses a single per CPU list shared by all
     rmlocks in	the system.  If	rmlocks	become popular,	hashing	to multiple
     per CPU queues may	be needed to speed up the writer lock process.

FreeBSD	9.3			 June 25, 2013			   FreeBSD 9.3

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=rmlock&sektion=9&manpath=FreeBSD+9.3-RELEASE>

home | help