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

FreeBSD Manual Pages


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

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

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

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

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

     rm_destroy(struct rmlock *rm);

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

     rm_wlock(struct rmlock *rm);

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

     rm_wunlock(struct rmlock *rm);

     rm_wowned(struct rmlock *rm);

     #include <sys/kernel.h>

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

     Mostly reader 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 had
     been locked for shared access is an expensive operation.

     Although reader/writer locks look very similar to sx(9) locks, their us-
     age pattern is different.	Reader/writer locks can	be treated as mutexes
     (see mutex(9)) with shared/exclusive semantics.  Unlike sx(9), an rmlock
     can be locked while holding a non-spin mutex, and an rmlock cannot	be
     held while	sleeping.  The rmlock locks have full priority propagation
     like mutexes.  The	rm_priotracker structure argument supplied in
     rm_rlock()	and rm_runlock() is used to keep track of the read owner(s).
     Another important property	is that	shared holders of rmlock can recurse
     if	the lock has been initialized with the LO_RECURSABLE option, however
     exclusive locks are not allowed to	recurse.

   Macros and Functions
     rm_init(struct rmlock *rm,	const char *name)
	     Initialize	structure located at rm	as mostly reader lock, de-
	     scribed by	name.  The name	description is used solely for debug-
	     ging purposes.  This function must	be called before any other op-
	     erations on the lock.

     rm_init_flags(struct rmlock *rm, const char *name,	int opts)
	     Initialize	the rm lock just like the rm_init() function, but
	     specifying	a set of optional flags	to alter the behaviour of rm,
	     through the opts argument.	 It contains one or more of the	fol-
	     lowing flags:

	     RM_NOWITNESS  Instruct witness(4) to ignore this lock.

	     RM_RECURSE	   Allow threads to recursively	acquire	exclusive
			   locks for rm.

     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
	     rmlocks cannot be held while sleeping.  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 LO_RECURSABLE option the rm_rlock() function can be
	     called when the thread has	already	acquired reader	access on rm.
	     This is called "recursing on a lock".

     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_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.

     locking(9), mutex(9), panic(9), rwlock(9),	sema(9), sx(9)

     These functions appeared in FreeBSD 7.0.

     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.

     The rmlock	implementation is currently not	optimized for single processor

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

     The rmlock	can currently not be used as a lock argument for condition
     variable wait functions.

BSD			       November	10, 2007			   BSD


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

home | help