Build urcu-qsbr.so library, update README

[urcu.git] / README

diff --git a/README b/README
index d47e5df9465070010a15797671ed48195dcf0628..93c0a742cedda21928f5333f93737409819f0908 100644 (file)
--- a/README
+++ b/README
@@ -1,11 +1,82 @@
-build instructions for userspace-rcu library :
+Userspace RCU Implementation
+by Mathieu Desnoyers and Paul E. McKenney
 
-make pthreads-x86
-or
-make pthreads-ppc
+BUILDING
+--------
 
-make
-make install
+       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 urcu 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.
+
+       Read-side critical sections can 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.
+
+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.
+       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.
 
 
-     Mathieu Desnoyers