Add coding style document

[urcu.git] / README

diff --git a/README b/README
index ec0d6a22b79c165a87cac300c6964e846f79c5a8..659de17d028c8e4ebbabed65b97ee1e3814cf99a 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


@@ -28,7 +29,7 @@ Currently, x86 (i386, i486, i586, i686), x86 64-bit, PowerPC 32/64, S390, S390x,
 ARM, Alpha, ia64 and Sparcv9 32/64 are supported. Only tested on Linux so
 far, but should theoretically work on other operating systems.
 
 ARM, Alpha, ia64 and Sparcv9 32/64 are supported. Only tested on Linux so
 far, but should theoretically work on other operating systems.
 

-ARM depends on running a Linux kernel 2.6.15 or better.
+ARM depends on running a Linux kernel 2.6.15 or better, GCC 4.4 or better.

 
 The gcc compiler versions 3.3, 3.4, 4.0, 4.1, 4.2, 4.3, 4.4 and 4.5 are
 supported, with the following exceptions:
 
 The gcc compiler versions 3.3, 3.4, 4.0, 4.1, 4.2, 4.3, 4.4 and 4.5 are
 supported, with the following exceptions:


@@ -38,8 +39,26 @@ 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

-- Alpha, ia64 and ARM architectures depend on 4.x gcc with atomic builtins
-  support.
+- 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 gcc 4.x with atomic builtins
+  support. For ARM this was introduced with gcc 4.4:
+    http://gcc.gnu.org/gcc-4.4/changes.html
+
+For developers using the git tree:
+
+This source tree is based on the autotools suite from GNU to simplify
+portability. Here are some things you should have on your system in order to
+compile the git repository tree :
+
+- GNU autotools (automake >=1.10, autoconf >=2.50, autoheader >=2.50)
+  (make sure your system wide "automake" points to a recent version!)
+- GNU Libtool >=2.2
+  (for more information, go to http://www.gnu.org/software/autoconf/)
+
+If you get the tree from the repository, you will need to use the "bootstrap"
+script in the root of the tree. It calls all the GNU tools needed to prepare the
+tree configuration.

 
 
 QUICK START GUIDE
 
 
 QUICK START GUIDE


@@ -124,22 +143,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 rcu-api.txt in userspace-rcu documentation 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


@@ -169,6 +203,15 @@ Interaction with mutexes
        mutex in its dependency chain) should not be acquired from within a RCU
        read-side critical section.
 
        mutex in its dependency chain) should not be acquired from within a RCU
        read-side critical section.
 

+       This is especially important to understand in the context of the
+       QSBR flavor: a registered reader thread being "online" by
+       default should be considered as within a RCU read-side critical
+       section unless explicitly put "offline". Therefore, if
+       synchronize_rcu() is called with a mutex held, this mutex, as
+       well as any mutex which has this mutex in its dependency chain
+       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
 Usage of DEBUG_RCU
 
        DEBUG_RCU is used to add internal debugging self-checks to the


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