[urcu.git] / README

Userspace RCU Implementation
by Mathieu Desnoyers and Paul E. McKenney

BUILDING
--------

	./bootstrap (skip if using tarball)
	./configure
	make
	make install
	

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

Usage of all urcu libraries

	* Define _LGPL_SOURCE (only) if your code is LGPL or GPL compatible
	  before including the urcu.h or urcu-qsbr.h header. If your application
	  is distributed under another license, function calls will be generated
	  instead of inlines, so your application can link with the library.
	* Linking with one of the libraries below is always necessary even for
	  LGPL and GPL applications.

Usage of liburcu

	* #include <urcu.h>
	* Link the application with "-lurcu".
	* This is the preferred version of the library, both in terms of speed
	  and flexibility. Requires a signal, typically SIGUSR1. Can be
	  overridden with -DSIGURCU by modifying Makefile.build.inc.

Usage of liburcu-mb

	* #include <urcu.h>
	* Compile any _LGPL_SOURCE code using this library with "-DURCU_MB".
	* Link with "-lurcu-mb".
	* This version of the urcu library does not need to
	  reserve a signal number. URCU_MB uses full memory barriers for
	  readers. This eliminates the need for signals but results in slower
	  reads.

Usage of liburcu-qsbr

	* #include <urcu-qsbr.h>
	* Link with "-lurcu-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. It provides the fastest read-side at the
	  expense of more intrusiveness in the application code.

Usage of liburcu-bp

	* #include <urcu-bp.h>
	* Link with "-lurcu-bp".
	* The BP library flavor stands for "bulletproof". It is specifically
	  designed to help tracing library to hook on applications without
	  requiring to modify these applications. urcu_init(),
	  rcu_register_thread() and rcu_unregister_thread() all become nops.
	  The state is dealt with by the library internally at the expense of
	  read-side and write-side performance.

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(). Unregistration
	must be performed before exiting the thread by using
	rcu_unregister_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.

Usage of liburcu-defer

	* #include <urcu-defer.h>
	* Link with "-lurcu-defer"
	* Provides call_rcu() primitive to enqueue delayed callbacks. Queued
	  callbacks are executed in batch periodically after a grace period.
	  Do _not_ use call_rcu() within a read-side critical section, because
	  it may call synchronize_rcu() if the thread queue is full.

Being careful with signals

	The liburcu 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). The liburcu-mb and liburcu-qsbr versions of the Userspace RCU
	library do not require any signal.

	Read-side critical sections 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().

	Read-side critical sections are _not_ allowed in a signal handler with
	liburcu-qsbr, unless signals are disabled explicitly around each
	rcu_quiescent_state() calls, when threads are put offline and around
	calls to synchronize_rcu(). Even then, we do not recommend it.

Usage of DEBUG_RCU

	DEBUG_RCU is used to add internal debugging self-checks to the
	RCU library. This define adds a performance penalty 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.
Commit	Line	Data
	1	Userspace RCU Implementation
	2	by Mathieu Desnoyers and Paul E. McKenney
	3
	4	BUILDING
	5	--------
	6
	7	./bootstrap (skip if using tarball)
	8	./configure
	9	make
	10	make install
	11
	12
	13	QUICK START GUIDE
	14	-----------------
	15
	16	Usage of all urcu libraries
	17
	18	* Define _LGPL_SOURCE (only) if your code is LGPL or GPL compatible
	19	before including the urcu.h or urcu-qsbr.h header. If your application
	20	is distributed under another license, function calls will be generated
	21	instead of inlines, so your application can link with the library.
	22	* Linking with one of the libraries below is always necessary even for
	23	LGPL and GPL applications.
	24
	25	Usage of liburcu
	26
	27	* #include <urcu.h>
	28	* Link the application with "-lurcu".
	29	* This is the preferred version of the library, both in terms of speed
	30	and flexibility. Requires a signal, typically SIGUSR1. Can be
	31	overridden with -DSIGURCU by modifying Makefile.build.inc.
	32
	33	Usage of liburcu-mb
	34
	35	* #include <urcu.h>
	36	* Compile any _LGPL_SOURCE code using this library with "-DURCU_MB".
	37	* Link with "-lurcu-mb".
	38	* This version of the urcu library does not need to
	39	reserve a signal number. URCU_MB uses full memory barriers for
	40	readers. This eliminates the need for signals but results in slower
	41	reads.
	42
	43	Usage of liburcu-qsbr
	44
	45	* #include <urcu-qsbr.h>
	46	* Link with "-lurcu-qsbr".
	47	* The QSBR flavor of RCU needs to have each reader thread executing
	48	rcu_quiescent_state() periodically to progress. rcu_thread_online()
	49	and rcu_thread_offline() can be used to mark long periods for which
	50	the threads are not active. It provides the fastest read-side at the
	51	expense of more intrusiveness in the application code.
	52
	53	Usage of liburcu-bp
	54
	55	* #include <urcu-bp.h>
	56	* Link with "-lurcu-bp".
	57	* The BP library flavor stands for "bulletproof". It is specifically
	58	designed to help tracing library to hook on applications without
	59	requiring to modify these applications. urcu_init(),
	60	rcu_register_thread() and rcu_unregister_thread() all become nops.
	61	The state is dealt with by the library internally at the expense of
	62	read-side and write-side performance.
	63
	64	Initialization
	65
	66	Each thread that has reader critical sections (that uses
	67	rcu_read_lock()/rcu_read_unlock() must first register to the URCU
	68	library. This is done by calling rcu_register_thread(). Unregistration
	69	must be performed before exiting the thread by using
	70	rcu_unregister_thread().
	71
	72	Reading
	73
	74	Reader critical sections must be protected by locating them between
	75	calls to rcu_read_lock() and rcu_read_unlock(). Inside that lock,
	76	rcu_dereference() may be called to read an RCU protected pointer.
	77
	78	Writing
	79
	80	rcu_assign_pointer() and rcu_xchg_pointer() may be called anywhere.
	81	After, synchronize_rcu() must be called. When it returns, the old
	82	values are not in usage anymore.
	83
	84	Usage of liburcu-defer
	85
	86	* #include <urcu-defer.h>
	87	* Link with "-lurcu-defer"
	88	* Provides call_rcu() primitive to enqueue delayed callbacks. Queued
	89	callbacks are executed in batch periodically after a grace period.
	90	Do _not_ use call_rcu() within a read-side critical section, because
	91	it may call synchronize_rcu() if the thread queue is full.
	92
	93	Being careful with signals
	94
	95	The liburcu library uses signals internally. The signal handler is
	96	registered with the SA_RESTART flag. However, these signals may cause
	97	some non-restartable system calls to fail with errno = EINTR. Care
	98	should be taken to restart system calls manually if they fail with this
	99	error. A list of non-restartable system calls may be found in
	100	signal(7). The liburcu-mb and liburcu-qsbr versions of the Userspace RCU
	101	library do not require any signal.
	102
	103	Read-side critical sections are allowed in a signal handler with
	104	liburcu and liburcu-mb. Be careful, however, to disable these signals
	105	between thread creation and calls to rcu_register_thread(), because a
	106	signal handler nesting on an unregistered thread would not be allowed to
	107	call rcu_read_lock().
	108
	109	Read-side critical sections are _not_ allowed in a signal handler with
	110	liburcu-qsbr, unless signals are disabled explicitly around each
	111	rcu_quiescent_state() calls, when threads are put offline and around
	112	calls to synchronize_rcu(). Even then, we do not recommend it.
	113
	114	Usage of DEBUG_RCU
	115
	116	DEBUG_RCU is used to add internal debugging self-checks to the
	117	RCU library. This define adds a performance penalty when enabled.
	118	Can be enabled by uncommenting the corresponding line in
	119	Makefile.build.inc.
	120
	121	Usage of DEBUG_YIELD
	122
	123	DEBUG_YIELD is used to add random delays in the code for testing
	124	purposes.