Rename CONFIG_URCU_AVOID_SIGNALS to URCU_MB, and README updates
authorMathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
Tue, 15 Sep 2009 23:38:36 +0000 (19:38 -0400)
committerMathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
Tue, 15 Sep 2009 23:38:36 +0000 (19:38 -0400)
Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
Makefile.build.inc
Makefile.inc
README
tests/Makefile.inc
urcu-static.h
urcu.c

index 56c7705690f0afb7dbffe6e6bdd3020d1aa34e56..3f05de97a397d0a1137deba17b01108ffc4f1874 100644 (file)
@@ -36,9 +36,6 @@ ifeq ("${HOSTTYPE}","s390x")
 ARCHTYPE=s390
 endif
 
-#Build the library without using signals. Slower read-side.
-#CFLAGS+=-DCONFIG_URCU_AVOID_SIGNALS
-
 #Changing the signal number used by the library. SIGUSR1 by default.
 #CFLAGS+=-DSIGURCU=SIGUSR2
 
index 14ba4edd07c38546e10f1728bdfdc3cfe367a92a..18609e94efd780fb862eebff331800df13de7b61 100644 (file)
@@ -29,7 +29,7 @@ urcu.o: urcu.c urcu.h
        $(CC) -fPIC ${CFLAGS} $(LDFLAGS) -c -o $@ $(SRC_DEP)
 
 urcu-mb.o: urcu.c urcu.h
-       $(CC) -fPIC -DCONFIG_URCU_AVOID_SIGNALS ${CFLAGS} $(LDFLAGS) -c -o $@ $(SRC_DEP)
+       $(CC) -fPIC -DURCU_MB ${CFLAGS} $(LDFLAGS) -c -o $@ $(SRC_DEP)
 
 urcu-qsbr.o: urcu-qsbr.c urcu-qsbr.h
        $(CC) -fPIC ${CFLAGS} $(LDFLAGS) -c -o $@ $(SRC_DEP)
diff --git a/README b/README
index 93c0a742cedda21928f5333f93737409819f0908..7753c8f957dfbf6acd9244b2fa2d9759879bc3f3 100644 (file)
--- a/README
+++ b/README
@@ -11,6 +11,43 @@ BUILDING
 QUICK START GUIDE
 -----------------
 
+Usage of all urcu libraries
+
+       * Define _LGPL_SOURCE (only) if your code is LGPL or GPL compatible
+         before including the urcu.h or urcu-qsbr.h header. If your application
+         is distributed under another license, function calls will be generated
+         instead of inlines, so your application can link with the library.
+       * Linking with one of the libraries below is always necessary even for
+         LGPL and GPL applications.
+
+Usage of liburcu
+
+       * #include <urcu.h>
+       * Link the application with "-lurcu".
+       * This is the preferred version of the library, both in terms of speed
+         and flexibility. Requires a signal, typically SIGUSR1. Can be
+         overridden with -DSIGURCU by modifying Makefile.build.inc.
+
+Usage of liburcu-mb
+
+       * #include <urcu.h>
+       * Compile code with "-DURCU_MB"
+       * Link with "-lurcu-mb".
+       * This version of the urcu library does not need to
+         reserve a signal number. URCU_MB uses full memory barriers for
+         readers. This eliminates the need for signals but results in slower
+         reads.
+
+Usage of liburcu-qsbr
+
+       * #include <urcu-qsbr.h>
+       * Link with "-lurcu-qsbr".
+       * The QSBR flavor of RCU needs to have each reader thread executing
+         rcu_quiescent_state() periodically to progress. rcu_thread_online()
+         and rcu_thread_offline() can be used to mark long periods for which
+         the threads are not active. It provides the fastest read-side at the
+         expense of more intrusiveness in the application code.
+
 Initialization
 
        Each thread that has reader critical sections (that uses
@@ -31,46 +68,29 @@ Writing
 
 Being careful with signals
 
-       The urcu library uses signals internally. The signal handler is
+       The liburcu library uses signals internally. The signal handler is
        registered with the SA_RESTART flag. However, these signals may cause
        some non-restartable system calls to fail with errno = EINTR. Care
        should be taken to restart system calls manually if they fail with this
        error. A list of non-restartable system calls may be found in
-       signal(7). To ensure the Userspace RCU library does not use signals,
-       see "Usage of liburcu-mb" below.
+       signal(7). The liburcu-mb and liburcu-qsbr versions of the Userspace RCU
+       library do not require any signal.
 
-       Read-side critical sections can are allowed in a signal handler with
+       Read-side critical sections are allowed in a signal handler with
        liburcu and liburcu-mb. Be careful, however, to disable these signals
        between thread creation and calls to rcu_register_thread(), because a
        signal handler nesting on an unregistered thread would not be allowed to
        call rcu_read_lock().
 
-Usage of liburcu
-
-       This is the preferred version of the library, both in terms of speed and
-       flexibility. Define _LGPL_SOURCE if your code is LGPL or GPL (otherwise
-       function calls will be generated instead of inlines). Use the urcu.h
-       header.  Link the application with "-lurcu".
-
-Usage of liburcu-mb
-
-       Compile code with "-DCONFIG_URCU_AVOID_SIGNALS" and link with
-       "-lurcu-mb" to use a version of the urcu library which does not need to
-       reserve a signal number. CONFIG_URCU_AVOID_SIGNALS uses full SMP
-       barriers for readers. This eliminates the need for signals but results
-       in slower reads.
-
-Usage of liburcu-qsbr
-
-       The QSBR flavor of RCU needs to have each reader thread executing
-       rcu_quiescent_state() periodically to progress. rcu_thread_online() and
-       rcu_thread_offline() can be used to mark long periods for which the
-       threads are not active. Link with "-lurcu-qsbr" and use urcu-qsbr.h.
+       Read-side critical sections are _not_ allowed in a signal handler with
+       liburcu-qsbr, unless signals are disabled explicitly around each
+       rcu_quiescent_state() calls, when threads are put offline and around
+       calls to synchronize_rcu(). Even then, we do not recommend it.
 
 Usage of DEBUG_RCU
 
        DEBUG_RCU is used to add internal debugging self-checks to the
-       RCU library. This define adds a performance penality when enabled.
+       RCU library. This define adds a performance penalty when enabled.
        Can be enabled by uncommenting the corresponding line in
        Makefile.build.inc.
 
@@ -78,5 +98,3 @@ Usage of DEBUG_YIELD
 
        DEBUG_YIELD is used to add random delays in the code for testing
        purposes.
-
-
index e99bfee8641e148a7b9613fcc6bdc6789008bbb5..56953f0b4494033ea1dee0b4a577effa5f826d06 100644 (file)
@@ -42,13 +42,13 @@ test_urcu_lgc: test_urcu_gc.c ${URCU_SIGNAL}
 
 
 test_urcu_mb: test_urcu.c ${URCU_MB}
-       $(CC) -DCONFIG_URCU_AVOID_SIGNALS ${CFLAGS} $(LDFLAGS) -o $@ $(SRC_DEP)
+       $(CC) -DURCU_MB ${CFLAGS} $(LDFLAGS) -o $@ $(SRC_DEP)
 
 test_urcu_gc_mb: test_urcu_gc.c ${URCU_MB}
-       $(CC) -DCONFIG_URCU_AVOID_SIGNALS ${CFLAGS} $(LDFLAGS) -o $@ $(SRC_DEP)
+       $(CC) -DURCU_MB ${CFLAGS} $(LDFLAGS) -o $@ $(SRC_DEP)
 
 test_urcu_lgc_mb: test_urcu_gc.c ${URCU_MB}
-       $(CC) -DTEST_LOCAL_GC -DCONFIG_URCU_AVOID_SIGNALS ${CFLAGS} $(LDFLAGS) -o $@ $(SRC_DEP)
+       $(CC) -DTEST_LOCAL_GC -DURCU_MB ${CFLAGS} $(LDFLAGS) -o $@ $(SRC_DEP)
 
 
 test_qsbr: test_qsbr.c ${URCU_QSBR}
index 0f3eba113d0efe8471b34d6d094496311c69ac12..0c6891e77ca0871f85cd1461333c0facd95bcf13 100644 (file)
 #define YIELD_WRITE    (1 << 1)
 
 /*
- * Updates without CONFIG_URCU_AVOID_SIGNALS are much slower. Account this in
+ * Updates without URCU_MB are much slower. Account this in
  * the delay.
  */
-#ifdef CONFIG_URCU_AVOID_SIGNALS
+#ifdef URCU_MB
 /* maximum sleep delay, in us */
 #define MAX_SLEEP 50
 #else
@@ -179,7 +179,7 @@ static inline void debug_yield_init(void)
 }
 #endif
 
-#ifdef CONFIG_URCU_AVOID_SIGNALS
+#ifdef URCU_MB
 static inline void reader_barrier()
 {
        smp_mb();
diff --git a/urcu.c b/urcu.c
index c210a1341ade8a189752417249bb47bca73a03aa..39f5619773ba383b402fb1c536672af990129ed3 100644 (file)
--- a/urcu.c
+++ b/urcu.c
@@ -36,7 +36,7 @@
 /* Do not #define _LGPL_SOURCE to ensure we can emit the wrapper symbols */
 #include "urcu.h"
 
-#ifndef CONFIG_URCU_AVOID_SIGNALS
+#ifndef URCU_MB
 void __attribute__((constructor)) urcu_init(void);
 void __attribute__((destructor)) urcu_exit(void);
 #else
@@ -127,7 +127,7 @@ static void switch_next_urcu_qparity(void)
        STORE_SHARED(urcu_gp_ctr, urcu_gp_ctr ^ RCU_GP_CTR_BIT);
 }
 
-#ifdef CONFIG_URCU_AVOID_SIGNALS
+#ifdef URCU_MB
 #ifdef HAS_INCOHERENT_CACHES
 static void force_mb_single_thread(struct reader_registry *index)
 {
@@ -139,7 +139,7 @@ static void force_mb_all_threads(void)
 {
        smp_mb();
 }
-#else /* #ifdef CONFIG_URCU_AVOID_SIGNALS */
+#else /* #ifdef URCU_MB */
 #ifdef HAS_INCOHERENT_CACHES
 static void force_mb_single_thread(struct reader_registry *index)
 {
@@ -206,7 +206,7 @@ static void force_mb_all_threads(void)
        }
        smp_mb();       /* read ->need_mb before ending the barrier */
 }
-#endif /* #else #ifdef CONFIG_URCU_AVOID_SIGNALS */
+#endif /* #else #ifdef URCU_MB */
 
 void wait_for_quiescent_state(void)
 {
@@ -420,7 +420,7 @@ void rcu_unregister_thread(void)
        internal_urcu_unlock();
 }
 
-#ifndef CONFIG_URCU_AVOID_SIGNALS
+#ifndef URCU_MB
 static void sigurcu_handler(int signo, siginfo_t *siginfo, void *context)
 {
        /*
@@ -473,4 +473,4 @@ void urcu_exit(void)
        assert(act.sa_sigaction == sigurcu_handler);
        free(registry);
 }
-#endif /* #ifndef CONFIG_URCU_AVOID_SIGNALS */
+#endif /* #ifndef URCU_MB */
This page took 0.039521 seconds and 4 git commands to generate.