[userspace-rcu.git] / README

Userspace RCU Implementatation
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 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,
	define CONFIG_URCU_AVOID_SIGNALS at compile-time.

Usage of CONFIG_URCU_AVOID_SIGNALS

	CONFIG_URCU_AVOID_SIGNALS uses full SMP barriers for readers. This
	eliminates the need for signals but results in slower reads.


Usage of DEBUG_YIELD

	DEBUG_YIELD is used to add random delays in the code for testing
	purposes.
Commit	Line	Data
c97ae6eb PMF	1	Userspace RCU Implementatation
c97ae6eb PMF	2	by Mathieu Desnoyers and Paul E. McKenney
6991f61a	3
c97ae6eb PMF	4	BUILDING
c97ae6eb PMF	5	--------
6991f61a	6
c97ae6eb PMF	7	make
	8	make install
	9
aa8c36e0	10
c97ae6eb PMF	11	QUICK START GUIDE
c97ae6eb PMF	12	-----------------
aa8c36e0	13
c97ae6eb PMF	14	Initialization
	15
	16	Each thread that has reader critical sections (that uses
	17	rcu_read_lock()/rcu_read_unlock() must first register to the URCU
	18	library. This is done by calling rcu_register_thread().
	19
	20	Reading
	21
	22	Reader critical sections must be protected by locating them between
	23	calls to rcu_read_lock() and rcu_read_unlock(). Inside that lock,
	24	rcu_dereference() may be called to read an RCU protected pointer.
	25
	26	Writing
	27
	28	rcu_assign_pointer() and rcu_xchg_pointer() may be called anywhere.
9fb223da MD	29	After, synchronize_rcu() must be called. When it returns, the old
9fb223da MD	30	values are not in usage anymore.
c97ae6eb	31
dd052bd3 PMF	32	Being careful with signals
	33
	34	The library uses signals internally. The signal handler is
	35	registered with the SA_RESTART flag. However, these signals may cause
	36	some non-restartable system calls to fail with errno = EINTR. Care
	37	should be taken to restart system calls manually if they fail with this
	38	error. A list of non-restartable system calls may be found in
b4ce1526 MD	39	signal(7). To ensure the Userspace RCU library does not use signals,
b4ce1526 MD	40	define CONFIG_URCU_AVOID_SIGNALS at compile-time.
c97ae6eb	41
b4ce1526	42	Usage of CONFIG_URCU_AVOID_SIGNALS
c97ae6eb	43
b4ce1526 MD	44	CONFIG_URCU_AVOID_SIGNALS uses full SMP barriers for readers. This
b4ce1526 MD	45	eliminates the need for signals but results in slower reads.
c97ae6eb PMF	46
	47
	48	Usage of DEBUG_YIELD
	49
	50	DEBUG_YIELD is used to add random delays in the code for testing
	51	purposes.