Discourage use of pthread_atfork() for call_rcu handlers

[urcu.git] / README

diff --git a/README b/README
index 303c6ec48fc0fd948de29d1bc1319e523d7eadd4..2d29c1d4e1c670800ec808a693f41cca2344ea0c 100644 (file)
--- a/README
+++ b/README
@@ -22,6 +22,7 @@ BUILDING
                Forcing a 32-bit build for Sparcv9 (typical for Sparc v9)
                * CFLAGS="-m32 -Wa,-Av9a -g -O2" ./configure
 
+
 ARCHITECTURES SUPPORTED
 -----------------------
 
@@ -66,6 +67,19 @@ 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
+- cmm_ : Concurrent Memory Model
+- caa_ : Concurrent Architecture Abstraction
+- cds_ : Concurrent Data Structures
+- uatomic_: Userspace Atomic
+
+
 QUICK START GUIDE
 -----------------
 
@@ -259,4 +273,24 @@ 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)
+
+       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.