Discourage use of pthread_atfork() for call_rcu handlers

[userspace-rcu.git] / README

diff --git a/README b/README
index ce25e3a3dabc8977f7a4dc5d4e391e5238e455fc..97fba69462cc6e862578b942715316d40dfedecb 100644 (file)
--- a/README
+++ b/README
@@ -253,3 +253,17 @@ Interaction with fork()
        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.