Rename CONFIG_URCU_AVOID_SIGNALS to URCU_MB, and README updates

[urcu.git] / README

diff --git a/README b/README
index 71cf729598bd8e5e9223246a3b5562bbaa017dd5..7753c8f957dfbf6acd9244b2fa2d9759879bc3f3 100644 (file)
--- a/README
+++ b/README
@@ -1,4 +1,4 @@
-Userspace RCU Implementatation
+Userspace RCU Implementation
 by Mathieu Desnoyers and Paul E. McKenney
 
 BUILDING
@@ -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
@@ -29,15 +66,35 @@ Writing
        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.
 
-Usage of DEBUG_FULL_MB
+       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().
 
-       DEBUG_FULL_MB uses full SMP barriers for readers. This eliminates the
-       need for signals but results in slower reads.
+       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.
-