projects / urcu.git / blame
| Commit | Line | Data |
|---|---|---|
| c97ae6eb PMF |
1 | Userspace RCU Implementatation |
| 2 | by Mathieu Desnoyers and Paul E. McKenney | |
| 6991f61a | 3 | |
| c97ae6eb PMF |
4 | BUILDING |
| 5 | -------- | |
| 6991f61a | 6 | |
| c97ae6eb PMF |
7 | make |
| 8 | make install | |
| 9 | ||
| aa8c36e0 | 10 | |
| c97ae6eb PMF |
11 | QUICK START GUIDE |
| 12 | ----------------- | |
| aa8c36e0 | 13 | |
| c97ae6eb PMF |
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. | |
| 9fb223da MD |
29 | After, synchronize_rcu() must be called. When it returns, the old |
| 30 | values are not in usage anymore. | |
| c97ae6eb | 31 | |
| dd052bd3 PMF |
32 | Being careful with signals |
| 33 | ||
| 34 | The 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 | |
| b4ce1526 MD |
39 | signal(7). To ensure the Userspace RCU library does not use signals, |
| 40 | define CONFIG_URCU_AVOID_SIGNALS at compile-time. | |
| c97ae6eb | 41 | |
| cee02f0a MD |
42 | Read-side critical sections can sit in a signal handler. Be careful, |
| 43 | however, to disable these signals between thread creation and calls to | |
| 44 | rcu_register_thread(), because a signal handler nesting on an | |
| 45 | unregistered thread would not be allowed to call rcu_read_lock(). | |
| 46 | ||
| b4ce1526 | 47 | Usage of CONFIG_URCU_AVOID_SIGNALS |
| c97ae6eb | 48 | |
| b4ce1526 MD |
49 | CONFIG_URCU_AVOID_SIGNALS uses full SMP barriers for readers. This |
| 50 | eliminates the need for signals but results in slower reads. | |
| c97ae6eb | 51 | |
| cee02f0a MD |
52 | Usage of DEBUG_RCU |
| 53 | ||
| 54 | DEBUG_RCU is used to add internal debugging self-checks to the | |
| 55 | RCU library. This define adds a performance penality when enabled. | |
| fb6e510b MD |
56 | Can be enabled by uncommenting the corresponding line in |
| 57 | Makefile.build.inc. | |
| c97ae6eb PMF |
58 | |
| 59 | Usage of DEBUG_YIELD | |
| 60 | ||
| 61 | DEBUG_YIELD is used to add random delays in the code for testing | |
| 62 | purposes. |