README: document each API file

[urcu.git] / README

diff --git a/README b/README
index 83330eab1e5ab82cd128dd6c68cdc247f1f272a8..e676757edf1b45cb56fbbe47aafcc2882eb1da45 100644 (file)
--- a/README
+++ b/README
@@ -73,11 +73,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,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.