Revert "qsbr urcu: make it safe to call rcu_sychronize from a registered thread."

[urcu.git] / README

Userspace RCU Implementation
by Mathieu Desnoyers and Paul E. McKenney

BUILDING
--------

	make
	make install
	

QUICK START GUIDE
-----------------

Initialization

	Each thread that has reader critical sections (that uses
	rcu_read_lock()/rcu_read_unlock() must first register to the URCU
	library. This is done by calling rcu_register_thread().

Reading

	Reader critical sections must be protected by locating them between
	calls to rcu_read_lock() and rcu_read_unlock(). Inside that lock,
	rcu_dereference() may be called to read an RCU protected pointer.

Writing

	rcu_assign_pointer() and rcu_xchg_pointer() may be called anywhere.
	After, synchronize_rcu() must be called. When it returns, the old
	values are not in usage anymore.

Being careful with signals

	The urcu library uses signals internally. The signal handler is
	registered with the SA_RESTART flag. However, these signals may cause
	some non-restartable system calls to fail with errno = EINTR. Care
	should be taken to restart system calls manually if they fail with this
	error. A list of non-restartable system calls may be found in
	signal(7). To ensure the Userspace RCU library does not use signals,
	see "Usage of liburcu-mb" below.

	Read-side critical sections can are allowed in a signal handler with
	liburcu and liburcu-mb. Be careful, however, to disable these signals
	between thread creation and calls to rcu_register_thread(), because a
	signal handler nesting on an unregistered thread would not be allowed to
	call rcu_read_lock().

Usage of liburcu

	This is the preferred version of the library, both in terms of speed and
	flexibility. Define _LGPL_SOURCE if your code is LGPL or GPL (otherwise
	function calls will be generated instead of inlines). Use the urcu.h
	header.  Link the application with "-lurcu".

Usage of liburcu-mb

	Compile code with "-DCONFIG_URCU_AVOID_SIGNALS" and link with
	"-lurcu-mb" to use a version of the urcu library which does not need to
	reserve a signal number. CONFIG_URCU_AVOID_SIGNALS uses full SMP
	barriers for readers. This eliminates the need for signals but results
	in slower reads.

Usage of liburcu-qsbr

	The QSBR flavor of RCU needs to have each reader thread executing
	rcu_quiescent_state() periodically to progress. rcu_thread_online() and
	rcu_thread_offline() can be used to mark long periods for which the
	threads are not active. Link with "-lurcu-qsbr" and use urcu-qsbr.h.

Usage of DEBUG_RCU

	DEBUG_RCU is used to add internal debugging self-checks to the
	RCU library. This define adds a performance penality when enabled.
	Can be enabled by uncommenting the corresponding line in
	Makefile.build.inc.

Usage of DEBUG_YIELD

	DEBUG_YIELD is used to add random delays in the code for testing
	purposes.