X-Git-Url: http://git.liburcu.org/?p=urcu.git;a=blobdiff_plain;f=README;h=ce498b939938868e06334e1e7d0aec87a5b5506f;hp=9d154c53832d471871f99ca0e4dc1ae5ec74109f;hb=882f335739b978d1c55be2faeed077f315afe5d7;hpb=1eade46a854eb8211be9fd32e0cf6835576deb63

diff --git a/README b/README
index 9d154c5..ce498b9 100644
--- a/README
+++ b/README
@@ -17,7 +17,7 @@ BUILDING
 		* CFLAGS="-m64 -g -O2" ./configure
 
 		Forcing a 32-bit build with 386 backward compatibility:
-		* CFLAGS="-m32 -g -O2" ./configure --target=i386-pc-linux-gnu
+		* CFLAGS="-m32 -g -O2" ./configure --host=i386-pc-linux-gnu
 
 		Forcing a 32-bit build for Sparcv9 (typical for Sparc v9)
 		* CFLAGS="-m32 -Wa,-Av9a -g -O2" ./configure
@@ -48,6 +48,8 @@ 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.
+
 For developers using the git tree:
 
 This source tree is based on the autotools suite from GNU to simplify
@@ -73,11 +75,11 @@ API
 See the relevant API documentation files in doc/. The APIs provided by
 Userspace RCU are, by prefix:
 
-- rcu_ : Read-Copy Update
+- rcu_ : Read-Copy Update (see doc/rcu-api.txt)
 - cmm_ : Concurrent Memory Model
 - caa_ : Concurrent Architecture Abstraction
-- cds_ : Concurrent Data Structures
-- uatomic_: Userspace Atomic
+- cds_ : Concurrent Data Structures (see doc/cds-api.txt)
+- uatomic_: Userspace Atomic (see doc/uatomic-api.txt)
 
 
 QUICK START GUIDE
@@ -232,6 +234,47 @@ Interaction with mutexes
 	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
@@ -253,24 +296,3 @@ SMP support
 		./configure --disable-smp-support
 
 	theoretically yielding slightly better performance.
-
-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().
-	These three APIs are suitable for passing to pthread_atfork().