Make defer_rcu() usable from library using multiple URCU implementations

[urcu.git] / README

diff --git a/README b/README
index b6d2ae48d0b3365ccd0aa4344bc95f24ed6daef3..7d97f1964674407ddb23c069e3024ea7dc2cfdd7 100644 (file)
--- a/README
+++ b/README
@@ -124,16 +124,15 @@ Writing
 
 Usage of liburcu-defer
 
 
 Usage of liburcu-defer
 

-       * #include <urcu-defer.h>
-       * Link with "-lurcu-defer", and also with one of the urcu library
-         (either urcu, urcu-bp, urcu-mb or urcu-qsbr).
+       * Follow instructions for either liburcu, liburcu-qsbr,
+         liburcu-mb, liburcu-signal, or liburcu-bp above.
+         The liburcu-defer functionality is pulled into each of
+         those library modules.

        * Provides defer_rcu() primitive to enqueue delayed callbacks. Queued
          callbacks are executed in batch periodically after a grace period.
          Do _not_ use defer_rcu() within a read-side critical section, because
          it may call synchronize_rcu() if the thread queue is full.
        * Provides defer_rcu() primitive to enqueue delayed callbacks. Queued
          callbacks are executed in batch periodically after a grace period.
          Do _not_ use defer_rcu() within a read-side critical section, because
          it may call synchronize_rcu() if the thread queue is full.

-       * Provides defer_rcu_ratelimit() primitive, which acts just like
-         defer_rcu(), but takes an additional rate limiter callback forcing
-         synchronized callback execution of the limiter returns non-zero.
+         This can lead to deadlock or worse.

        * Requires that rcu_defer_barrier() must be called in library destructor
          if a library queues callbacks and is expected to be unloaded with
          dlclose().
        * Requires that rcu_defer_barrier() must be called in library destructor
          if a library queues callbacks and is expected to be unloaded with
          dlclose().


@@ -201,6 +200,13 @@ Interaction with fork()
        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
        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 this case by requiring a call to
-       synchronize_rcu() following the fork() in the child before any new
-       thread is created.
+       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().