README

   1 Userspace RCU Implementation
   2 by Mathieu Desnoyers and Paul E. McKenney
   3
   4 BUILDING
   5 --------
   6
   7         make
   8         make install
   9
  10
  11 QUICK START GUIDE
  12 -----------------
  13
  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.
  29         After, synchronize_rcu() must be called. When it returns, the old
  30         values are not in usage anymore.
  31
  32 Being careful with signals
  33
  34         The urcu 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
  39         signal(7). To ensure the Userspace RCU library does not use signals,
  40         see "Usage of liburcu-mb" below.
  41
  42         Read-side critical sections can are allowed in a signal handler with
  43         liburcu and liburcu-mb. Be careful, however, to disable these signals
  44         between thread creation and calls to rcu_register_thread(), because a
  45         signal handler nesting on an unregistered thread would not be allowed to
  46         call rcu_read_lock().
  47
  48 Usage of liburcu
  49
  50         This is the preferred version of the library, both in terms of speed and
  51         flexibility. Define _LGPL_SOURCE if your code is LGPL or GPL (otherwise
  52         function calls will be generated instead of inlines). Use the urcu.h
  53         header.  Link the application with "-lurcu".
  54
  55 Usage of liburcu-mb
  56
  57         Compile code with "-DCONFIG_URCU_AVOID_SIGNALS" and link with
  58         "-lurcu-mb" to use a version of the urcu library which does not need to
  59         reserve a signal number. CONFIG_URCU_AVOID_SIGNALS uses full SMP
  60         barriers for readers. This eliminates the need for signals but results
  61         in slower reads.
  62
  63 Usage of liburcu-qsbr
  64
  65         The QSBR flavor of RCU needs to have each reader thread executing
  66         rcu_quiescent_state() periodically to progress. rcu_thread_online() and
  67         rcu_thread_offline() can be used to mark long periods for which the
  68         threads are not active. Link with "-lurcu-qsbr" and use urcu-qsbr.h.
  69
  70 Usage of DEBUG_RCU
  71
  72         DEBUG_RCU is used to add internal debugging self-checks to the
  73         RCU library. This define adds a performance penality when enabled.
  74         Can be enabled by uncommenting the corresponding line in
  75         Makefile.build.inc.
  76
  77 Usage of DEBUG_YIELD
  78
  79         DEBUG_YIELD is used to add random delays in the code for testing
  80         purposes.
  81
  82