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