[urcu.git] / README

Userspace RCU Implementation
by Mathieu Desnoyers and Paul E. McKenney

BUILDING
--------

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

	Note:	Forcing 32-bit build:
		* CFLAGS=-m32 ./configure

		Forcing 64-bit build:
		* CFLAGS=-m64 ./configure

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