Restrict supported arch ot P6+ on Intel x86 32.
[urcu.git] / README
CommitLineData
7ac06cef 1Userspace RCU Implementation
c97ae6eb 2by Mathieu Desnoyers and Paul E. McKenney
6991f61a 3
c97ae6eb
PMF
4BUILDING
5--------
6991f61a 6
48d848c7
PMF
7 ./bootstrap (skip if using tarball)
8 ./configure
c97ae6eb
PMF
9 make
10 make install
9ca52251
MD
11
12 Note: Forcing 32-bit build:
13 * CFLAGS=-m32 ./configure
14
15 Forcing 64-bit build:
16 * CFLAGS=-m64 ./configure
aa8c36e0 17
c51e75e6
MD
18ARCHITECTURES SUPPORTED
19-----------------------
20
64c4cafd 21Currently, x86 (only P6+), x86 64, PowerPC 32/64 and S390 are
c51e75e6
MD
22supported. The current use of sys_futex() makes it Linux-dependent, although
23this portability limitation might go away in a near future by using the pthread
64c4cafd
MD
24cond vars. Also, the restriction against i386, i486 and Pentium might go away if
25we integrate some of glibc runtime CPU-detection tests.
c51e75e6 26
c97ae6eb
PMF
27QUICK START GUIDE
28-----------------
aa8c36e0 29
0a1d290b
MD
30Usage of all urcu libraries
31
32 * Define _LGPL_SOURCE (only) if your code is LGPL or GPL compatible
33 before including the urcu.h or urcu-qsbr.h header. If your application
34 is distributed under another license, function calls will be generated
35 instead of inlines, so your application can link with the library.
36 * Linking with one of the libraries below is always necessary even for
37 LGPL and GPL applications.
38
39Usage of liburcu
40
41 * #include <urcu.h>
42 * Link the application with "-lurcu".
43 * This is the preferred version of the library, both in terms of speed
44 and flexibility. Requires a signal, typically SIGUSR1. Can be
45 overridden with -DSIGURCU by modifying Makefile.build.inc.
46
47Usage of liburcu-mb
48
49 * #include <urcu.h>
256dd999 50 * Compile any _LGPL_SOURCE code using this library with "-DURCU_MB".
0a1d290b
MD
51 * Link with "-lurcu-mb".
52 * This version of the urcu library does not need to
53 reserve a signal number. URCU_MB uses full memory barriers for
54 readers. This eliminates the need for signals but results in slower
55 reads.
56
57Usage of liburcu-qsbr
58
59 * #include <urcu-qsbr.h>
60 * Link with "-lurcu-qsbr".
61 * The QSBR flavor of RCU needs to have each reader thread executing
62 rcu_quiescent_state() periodically to progress. rcu_thread_online()
63 and rcu_thread_offline() can be used to mark long periods for which
64 the threads are not active. It provides the fastest read-side at the
65 expense of more intrusiveness in the application code.
66
fdee2e6d
MD
67Usage of liburcu-bp
68
69 * #include <urcu-bp.h>
70 * Link with "-lurcu-bp".
71 * The BP library flavor stands for "bulletproof". It is specifically
72 designed to help tracing library to hook on applications without
73 requiring to modify these applications. urcu_init(),
74 rcu_register_thread() and rcu_unregister_thread() all become nops.
75 The state is dealt with by the library internally at the expense of
76 read-side and write-side performance.
77
c97ae6eb
PMF
78Initialization
79
80 Each thread that has reader critical sections (that uses
81 rcu_read_lock()/rcu_read_unlock() must first register to the URCU
4c1471de
MD
82 library. This is done by calling rcu_register_thread(). Unregistration
83 must be performed before exiting the thread by using
84 rcu_unregister_thread().
c97ae6eb
PMF
85
86Reading
87
88 Reader critical sections must be protected by locating them between
89 calls to rcu_read_lock() and rcu_read_unlock(). Inside that lock,
90 rcu_dereference() may be called to read an RCU protected pointer.
91
92Writing
93
94 rcu_assign_pointer() and rcu_xchg_pointer() may be called anywhere.
9fb223da
MD
95 After, synchronize_rcu() must be called. When it returns, the old
96 values are not in usage anymore.
c97ae6eb 97
ec4e58a3
MD
98Usage of liburcu-defer
99
100 * #include <urcu-defer.h>
101 * Link with "-lurcu-defer"
102 * Provides call_rcu() primitive to enqueue delayed callbacks. Queued
103 callbacks are executed in batch periodically after a grace period.
104 Do _not_ use call_rcu() within a read-side critical section, because
105 it may call synchronize_rcu() if the thread queue is full.
106
dd052bd3
PMF
107Being careful with signals
108
0a1d290b 109 The liburcu library uses signals internally. The signal handler is
dd052bd3
PMF
110 registered with the SA_RESTART flag. However, these signals may cause
111 some non-restartable system calls to fail with errno = EINTR. Care
112 should be taken to restart system calls manually if they fail with this
113 error. A list of non-restartable system calls may be found in
0a1d290b
MD
114 signal(7). The liburcu-mb and liburcu-qsbr versions of the Userspace RCU
115 library do not require any signal.
c97ae6eb 116
0a1d290b 117 Read-side critical sections are allowed in a signal handler with
7ac06cef
MD
118 liburcu and liburcu-mb. Be careful, however, to disable these signals
119 between thread creation and calls to rcu_register_thread(), because a
120 signal handler nesting on an unregistered thread would not be allowed to
121 call rcu_read_lock().
cee02f0a 122
0a1d290b
MD
123 Read-side critical sections are _not_ allowed in a signal handler with
124 liburcu-qsbr, unless signals are disabled explicitly around each
125 rcu_quiescent_state() calls, when threads are put offline and around
126 calls to synchronize_rcu(). Even then, we do not recommend it.
c97ae6eb 127
cee02f0a
MD
128Usage of DEBUG_RCU
129
130 DEBUG_RCU is used to add internal debugging self-checks to the
0a1d290b 131 RCU library. This define adds a performance penalty when enabled.
fb6e510b
MD
132 Can be enabled by uncommenting the corresponding line in
133 Makefile.build.inc.
c97ae6eb
PMF
134
135Usage of DEBUG_YIELD
136
137 DEBUG_YIELD is used to add random delays in the code for testing
138 purposes.
This page took 0.040946 seconds and 4 git commands to generate.