X-Git-Url: http://git.liburcu.org/?p=urcu.git;a=blobdiff_plain;f=README;h=7753c8f957dfbf6acd9244b2fa2d9759879bc3f3;hp=93c0a742cedda21928f5333f93737409819f0908;hb=0a1d290b4432036a7c1bf4a1b251ec9086036a87;hpb=b39e3baec9feaf3623461eff85f08f216f3bb492

diff --git a/README b/README
index 93c0a74..7753c8f 100644
--- a/README
+++ b/README
@@ -11,6 +11,43 @@ BUILDING
 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 code 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
@@ -31,46 +68,29 @@ Writing
 
 Being careful with signals
 
-	The urcu library uses signals internally. The signal handler is
+	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). To ensure the Userspace RCU library does not use signals,
-	see "Usage of liburcu-mb" below.
+	signal(7). The liburcu-mb and liburcu-qsbr versions of the Userspace RCU
+	library do not require any signal.
 
-	Read-side critical sections can are allowed in a signal handler with
+	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().
 
-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.
+	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 penality when enabled.
+	RCU library. This define adds a performance penalty when enabled.
 	Can be enabled by uncommenting the corresponding line in
 	Makefile.build.inc.
 
@@ -78,5 +98,3 @@ Usage of DEBUG_YIELD
 
 	DEBUG_YIELD is used to add random delays in the code for testing
 	purposes.
-
-