X-Git-Url: http://git.liburcu.org/?p=urcu.git;a=blobdiff_plain;f=README;h=b47fe48c2c181e833c633c8b6b973ddcbf0f5186;hp=02cec268ac359d988d1ce3c811b2980e98ae385d;hb=ba59a0c7b244a0939a2298fc76a9002436ef9674;hpb=0d21ab2de8ec0b6607654e0122a1302639d6fe5b

diff --git a/README b/README
index 02cec26..b47fe48 100644
--- a/README
+++ b/README
@@ -1,14 +1,104 @@
-build instructions for userspace-rcu library :
+Userspace RCU Implementation
+by Mathieu Desnoyers and Paul E. McKenney
 
-make
-make install
+BUILDING
+--------
 
-Usage :
+	make
+	#force 32-bit build with: make -f Makefile32
+	#force 64-bit build with: make -f Makefile64
+	make install
+	
 
-Registration of _each thread_ calling read-side critical sections must be done
-with rcu_register_thread() before using rcu_read_lock()/rcu_read_unlock().
+QUICK START GUIDE
+-----------------
 
-Unregistration should be performed with rcu_unregister_thread() before exiting
-the thread.
+Usage of all urcu libraries
 
-     Mathieu Desnoyers
+	* 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.
+
+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.
+
+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.