X-Git-Url: https://git.liburcu.org/?a=blobdiff_plain;f=README;h=9554d2141875289a8e1ef3fb7b1df9a7f5145ba3;hb=74093738f199e3109f1d4ef0ce87b434ddc03e3f;hp=83330eab1e5ab82cd128dd6c68cdc247f1f272a8;hpb=75478b32ffe53b0d8b5e687d9cf7ebdd77a085de;p=urcu.git

diff --git a/README b/README
index 83330ea..9554d21 100644
--- a/README
+++ b/README
@@ -232,28 +232,6 @@ Interaction with mutexes
 	should only be taken when the RCU reader thread is "offline"
 	(this can be performed by calling rcu_thread_offline()).
 
-Usage of DEBUG_RCU
-
-	DEBUG_RCU is used to add internal debugging self-checks to the
-	RCU library. This define adds a performance penalty when enabled.
-	Can be enabled by uncommenting the corresponding line in
-	Makefile.build.inc.
-
-Usage of DEBUG_YIELD
-
-	DEBUG_YIELD is used to add random delays in the code for testing
-	purposes.
-
-SMP support
-
-	By default the library is configured to use synchronization primitives
-	adequate for SMP systems. On uniprocessor systems, support for SMP
-	systems can be disabled with:
-
-		./configure --disable-smp-support
-
-	theoretically yielding slightly better performance.
-
 Interaction with fork()
 
 	Special care must be taken for applications performing fork() without
@@ -273,7 +251,20 @@ Interaction with fork()
 	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().
+	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)
 
@@ -281,3 +272,25 @@ Thread Local Storage (TLS)
 	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
+	RCU library. This define adds a performance penalty when enabled.
+	Can be enabled by uncommenting the corresponding line in
+	Makefile.build.inc.
+
+Usage of DEBUG_YIELD
+
+	DEBUG_YIELD is used to add random delays in the code for testing
+	purposes.
+
+SMP support
+
+	By default the library is configured to use synchronization primitives
+	adequate for SMP systems. On uniprocessor systems, support for SMP
+	systems can be disabled with:
+
+		./configure --disable-smp-support
+
+	theoretically yielding slightly better performance.