Forcing a 32-bit build for Sparcv9 (typical for Sparc v9)
* CFLAGS="-m32 -Wa,-Av9a -g -O2" ./configure
+
ARCHITECTURES SUPPORTED
-----------------------
-Currently, x86 (i386, i486, i586, i686), x86 64-bit, PowerPC 32/64, S390, S390x,
-ARM, Alpha, ia64 and Sparcv9 32/64 are supported. Only tested on Linux so
-far, but should theoretically work on other operating systems.
+Currently, Linux x86 (i386, i486, i586, i686), x86 64-bit, PowerPC 32/64,
+S390, S390x, ARM, MIPS, Alpha, ia64 and Sparcv9 32/64 are supported.
+Tested on Linux, FreeBSD 8.2/8.3/9.0/9.1/10.0 i386/amd64, and Cygwin.
+Should also work on: Android, NetBSD 5, OpenBSD, Darwin (more testing
+needed before claiming support for these OS).
-ARM depends on running a Linux kernel 2.6.15 or better, GCC 4.4 or better.
+Linux ARM depends on running a Linux kernel 2.6.15 or better, GCC 4.4 or
+better.
The gcc compiler versions 3.3, 3.4, 4.0, 4.1, 4.2, 4.3, 4.4 and 4.5 are
supported, with the following exceptions:
support. For ARM this was introduced with gcc 4.4:
http://gcc.gnu.org/gcc-4.4/changes.html
+Clang version 3.0 (based on LLVM 3.0) is supported.
+
+Building on MacOS X (Darwin) requires a work-around for processor
+detection:
+ # 32-bit
+ ./configure --build=i686-apple-darwin11
+ # 64-bit
+ ./configure --build=x86_64-apple-darwin11
+
For developers using the git tree:
This source tree is based on the autotools suite from GNU to simplify
script in the root of the tree. It calls all the GNU tools needed to prepare the
tree configuration.
+Test scripts provided in the tests/ directory of the source tree depend
+on "bash" and the "seq" program.
+
+
+API
+---
+
+See the relevant API documentation files in doc/. The APIs provided by
+Userspace RCU are, by prefix:
+
+- rcu_ : Read-Copy Update (see doc/rcu-api.txt)
+- cmm_ : Concurrent Memory Model
+- caa_ : Concurrent Architecture Abstraction
+- cds_ : Concurrent Data Structures (see doc/cds-api.txt)
+- uatomic_: Userspace Atomic (see doc/uatomic-api.txt)
+
QUICK START GUIDE
-----------------
instead of inlines, so your application can link with the library.
* Linking with one of the libraries below is always necessary even for
LGPL and GPL applications.
+ * Define URCU_INLINE_SMALL_FUNCTIONS before including Userspace RCU
+ headers if you want Userspace RCU to inline small functions (10
+ lines or less) into the application. It can be used by applications
+ distributed under any kind of license, and does *not* make the
+ application a derived work of Userspace RCU.
+
+ Those small inlined functions are guaranteed to match the library
+ content as long as the library major version is unchanged.
+ Therefore, the application *must* be compiled with headers matching
+ the library major version number. Applications using
+ URCU_INLINE_SMALL_FUNCTIONS may be unable to use debugging
+ features of Userspace RCU without being recompiled.
+
Usage of liburcu
signal(7). The liburcu-mb and liburcu-qsbr versions of the Userspace RCU
library do not require any signal.
- Read-side critical sections are allowed in a signal handler with
- liburcu and liburcu-mb. Be careful, however, to disable these signals
+ Read-side critical sections are allowed in a signal handler,
+ except those setup with sigaltstack(2), 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().
+ signal handler nesting on an unregistered thread would not be
+ allowed to call rcu_read_lock().
Read-side critical sections are _not_ allowed in a signal handler with
liburcu-qsbr, unless signals are disabled explicitly around each
should only be taken when the RCU reader thread is "offline"
(this can be performed by calling rcu_thread_offline()).
+Interaction with fork()
+
+ Special care must be taken for applications performing fork() without
+ any following exec(). This is caused by the fact that Linux only clones
+ the thread calling fork(), and thus never replicates any of the other
+ parent thread into the child process. Most liburcu implementations
+ require that all registrations (as reader, defer_rcu and call_rcu
+ threads) should be released before a fork() is performed, except for the
+ rather common scenario where fork() is immediately followed by exec() in
+ the child process. The only implementation not subject to that rule is
+ liburcu-bp, which is designed to handle fork() by calling
+ rcu_bp_before_fork, rcu_bp_after_fork_parent and
+ rcu_bp_after_fork_child.
+
+ Applications that use call_rcu() and that fork() without
+ doing an immediate exec() must take special action. The parent
+ must invoke call_rcu_before_fork() before the fork() and
+ call_rcu_after_fork_parent() after the fork(). The child
+ process must invoke call_rcu_after_fork_child().
+ Even though these three APIs are suitable for passing to
+ pthread_atfork(), use of pthread_atfork() is *STRONGLY
+ DISCOURAGED* for programs calling the glibc memory allocator
+ (malloc(), calloc(), free(), ...) within call_rcu callbacks.
+ This is due to limitations in the way glibc memory allocator
+ handles calls to the memory allocator from concurrent threads
+ while the pthread_atfork() handlers are executing.
+ Combining e.g.:
+ * call to free() from callbacks executed within call_rcu worker
+ threads,
+ * executing call_rcu atfork handlers within the glibc pthread
+ atfork mechanism,
+ will sometimes trigger interesting process hangs. This usually
+ hangs on a memory allocator lock within glibc.
+
+Thread Local Storage (TLS)
+
+ Userspace RCU can fall back on pthread_getspecific() to emulate
+ TLS variables on systems where it is not available. This behavior
+ can be forced by specifying --disable-compiler-tls as configure
+ argument.
+
Usage of DEBUG_RCU
DEBUG_RCU is used to add internal debugging self-checks to the
theoretically yielding slightly better performance.
-Interaction with fork()
+MAKE TARGETS
+------------
- Special care must be taken for applications performing fork() without
- any following exec(). This is caused by the fact that Linux only clones
- the thread calling fork(), and thus never replicates any of the other
- parent thread into the child process. Most liburcu implementations
- require that all registrations (as reader, defer_rcu and call_rcu
- threads) should be released before a fork() is performed, except for the
- rather common scenario where fork() is immediately followed by exec() in
- the child process. The only implementation not subject to that rule is
- liburcu-bp, which is designed to handle fork() by calling
- rcu_bp_before_fork, rcu_bp_after_fork_parent and
- rcu_bp_after_fork_child.
+In addition to the usual "make check" target, Userspace RCU features
+"make regtest" and "make bench" targets.
- Applications that use call_rcu() and that fork() without
- doing an immediate exec() must take special action. The parent
- must invoke call_rcu_before_fork() before the fork() and
- call_rcu_after_fork_parent() after the fork(). The child
- process must invoke call_rcu_after_fork_child().
- These three APIs are suitable for passing to pthread_atfork().
+make check: Short tests, meant to be run when rebuilding or porting
+ Userspace RCU.
+
+make regtest: Long (many hours) test, meant to be run when modifying
+ Userspace RCU or porting it to a new architecture or
+ operating system.
+
+make bench: Long (many hours) benchmarks.
+
+CONTACTS
+--------
+
+You can contact the maintainers on the following mailing list:
+lttng-dev@lists.lttng.org
projects / urcu.git / blobdiff