From: Mathieu Desnoyers Date: Tue, 15 Sep 2009 23:38:36 +0000 (-0400) Subject: Rename CONFIG_URCU_AVOID_SIGNALS to URCU_MB, and README updates X-Git-Tag: v0.1~88 X-Git-Url: http://git.liburcu.org/?p=urcu.git;a=commitdiff_plain;h=0a1d290b4432036a7c1bf4a1b251ec9086036a87 Rename CONFIG_URCU_AVOID_SIGNALS to URCU_MB, and README updates Signed-off-by: Mathieu Desnoyers --- diff --git a/Makefile.build.inc b/Makefile.build.inc index 56c7705..3f05de9 100644 --- a/Makefile.build.inc +++ b/Makefile.build.inc @@ -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 diff --git a/Makefile.inc b/Makefile.inc index 14ba4ed..18609e9 100644 --- a/Makefile.inc +++ b/Makefile.inc @@ -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 93c0a74..7753c8f 100644 --- 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 + * 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 + * 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 + * 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. - - diff --git a/tests/Makefile.inc b/tests/Makefile.inc index e99bfee..56953f0 100644 --- a/tests/Makefile.inc +++ b/tests/Makefile.inc @@ -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} diff --git a/urcu-static.h b/urcu-static.h index 0f3eba1..0c6891e 100644 --- a/urcu-static.h +++ b/urcu-static.h @@ -133,10 +133,10 @@ #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 c210a13..39f5619 100644 --- 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 */