Merge branch 'master' into urcu/ht

[urcu.git] / README

diff --git a/README b/README
index ec0d6a22b79c165a87cac300c6964e846f79c5a8..1e76f2d1b098bb9579d573fcf8f36211c3c7c5f9 100644 (file)
--- a/README
+++ b/README
@@ -8,6 +8,7 @@ BUILDING
        ./configure
        make
        make install
        ./configure
        make
        make install

+       ldconfig

 
        Hints:  Forcing 32-bit build:
                * CFLAGS="-m32 -g -O2" ./configure
 
        Hints:  Forcing 32-bit build:
                * CFLAGS="-m32 -g -O2" ./configure


@@ -38,6 +39,8 @@ supported, with the following exceptions:
   therefore not compatible with liburcu on x86 32-bit (i386, i486, i586, i686).
   The problem has been reported to the gcc community:
     http://www.mail-archive.com/gcc-bugs@gcc.gnu.org/msg281255.html
   therefore not compatible with liburcu on x86 32-bit (i386, i486, i586, i686).
   The problem has been reported to the gcc community:
     http://www.mail-archive.com/gcc-bugs@gcc.gnu.org/msg281255.html

+- gcc 3.3 cannot match the "xchg" instruction on 32-bit x86 build.
+  See: http://kerneltrap.org/node/7507

 - Alpha, ia64 and ARM architectures depend on 4.x gcc with atomic builtins
   support.
 
 - Alpha, ia64 and ARM architectures depend on 4.x gcc with atomic builtins
   support.
 


@@ -124,22 +127,37 @@ 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().
        * Its API is currently experimental. It may change in future library
          releases.
 
        * Requires that rcu_defer_barrier() must be called in library destructor
          if a library queues callbacks and is expected to be unloaded with
          dlclose().
        * Its API is currently experimental. It may change in future library
          releases.
 

+Usage of urcu-call-rcu
+
+       * Follow instructions for either liburcu, liburcu-qsbr,
+         liburcu-mb, liburcu-signal, or liburcu-bp above.
+         The urcu-call-rcu functionality is provided for each of
+         these library modules.
+       * Provides the call_rcu() primitive to enqueue delayed callbacks
+         in a manner similar to defer_rcu(), but without ever delaying
+         for a grace period.  On the other hand, call_rcu()'s best-case
+         overhead is not quite as good as that of defer_rcu().
+       * Provides call_rcu() to allow asynchronous handling of RCU
+         grace periods.  A number of additional functions are provided
+         to manage the helper threads used by call_rcu(), but reasonable
+         defaults are used if these additional functions are not invoked.
+         See API.txt for more details.
+

 Being careful with signals
 
        The liburcu library uses signals internally. The signal handler is
 Being careful with signals
 
        The liburcu library uses signals internally. The signal handler is


@@ -201,4 +219,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.
+       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().