X-Git-Url: http://git.liburcu.org/?a=blobdiff_plain;f=README.md;h=58db299018deb07f36fbdd1bad863ed35f82b3e0;hb=546d9a117ef442847203e82f6b1bf6abd2d13b25;hp=8f19e18c2dd849b8868ad01fe0c6caba9c171fe5;hpb=af9254ab1cdee36cd7b68d52a49ba6a25d54b1c4;p=userspace-rcu.git diff --git a/README.md b/README.md index 8f19e18..58db299 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ + + Userspace RCU Implementation ============================ @@ -55,8 +61,7 @@ Currently, the following architectures are supported: Tested on: - Linux all architectures - - FreeBSD 8.2/8.3/9.0/9.1/10.0 i386/amd64 - - Solaris 10/11 i386 + - FreeBSD 13 i386/amd64 - Cygwin i386/amd64 - MacOS amd64/arm64 @@ -65,18 +70,19 @@ Should also work on: - Android - NetBSD 5 - OpenBSD - - Darwin + - Solaris (more testing needed before claiming support for these OS). -Linux ARM depends on running a Linux kernel 2.6.15 or better, GCC 4.4 or -better. -The C compiler used needs to support at least C99. The C++ compiler used -needs to support at least C++11. +Toolchain support +----------------- -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 C compiler used needs to support at least C99. The C++ compiler used needs +to support at least C++11. The oldest GCC version officialy supported and +tested is 4.8. + +Older GCC versions might still work with the following exceptions: - GCC 3.3 and 3.4 have a bug that prevents them from generating volatile accesses to offsets in a TLS structure on 32-bit x86. These versions are @@ -97,6 +103,10 @@ Clang version 3.0 (based on LLVM 3.0) is supported. Glibc >= 2.4 should work but the older version we test against is currently 2.17. + +Build system +------------ + For developers using the Git tree: This source tree is based on the autotools suite from GNU to simplify @@ -176,7 +186,7 @@ This is the preferred version of the library, in terms of grace-period detection speed, read-side speed and flexibility. Dynamically detects kernel support for `sys_membarrier()`. Falls back on `urcu-mb` scheme if support is not present, which has slower -read-side. Use the --disable-sys-membarrier-fallback configure option +read-side. Use the `--disable-sys-membarrier-fallback` configure option to disable the fall back, thus requiring `sys_membarrier()` to be available. This gives a small speedup when `sys_membarrier()` is supported by the kernel, and aborts in the library constructor if not @@ -210,9 +220,10 @@ results in slower reads. 1. `#include ` 2. Link the application with `-lurcu-signal` -Version of the library that requires a signal, typically `SIGUSR1`. Can -be overridden with `-DSIGRCU` by modifying `Makefile.build.inc`. - +NOTE: The `liburcu-signal` flavor is *deprecated* and will be removed in the +future. It is now identical to `liburcu-mb` at the exception of the symbols and +public header files. It is therefore slower than previous versions. Users are +encouraged to migrate to the `liburcu-memb` flavor. ### Usage of `liburcu-bp` @@ -251,6 +262,14 @@ protected pointer. After, `urcu__synchronize_rcu()` must be called. When it returns, the old values are not in usage anymore. +As an alternative to `urcu__synchronize_rcu()`, +it is also possible to use the urcu polling mechanism to wait for a +grace period to elapse. This can be done by using +`urcu__start_poll_synchronize_rcu()` +to start the grace period polling, and then invoke +`urcu__poll_state_synchronize_rcu()`, which returns true if +the grace period has completed, false otherwise. + ### Usage of `liburcu-defer` @@ -414,7 +433,7 @@ theoretically yielding slightly better performance. By default the library is configured with extra debugging checks for lock-free hash table iterator traversal disabled. -Building liburcu with --enable-cds-lfht-iter-debug and rebuilding +Building liburcu with `--enable-cds-lfht-iter-debug` and rebuilding application to match the ABI change allows finding cases where the hash table iterator is re-purposed to be used on a different hash table while still being used to iterate on a hash table. @@ -422,6 +441,10 @@ still being used to iterate on a hash table. This option alters the rculfhash ABI. Make sure to compile both library and application with matching configuration. +### Usage of `--enable-compiler-atomic-builtins` + +Building liburcu with `--enable-compiler-atomic-builtins` implements the uatomic +API with the compiler atomic builtins if supported. Make targets ------------ @@ -448,7 +471,7 @@ follows: - An application executable is built with `_LGPL_SOURCE` defined, includes any of the Userspace RCU 0.10 urcu flavor headers, and is built - without the -fpic compiler option. + without the `-fpic` compiler option. - The Userspace RCU 0.10 library shared objects are updated to 0.11 or 0.12 without rebuilding the application. @@ -460,7 +483,7 @@ Some possible work-arounds for this are: - Rebuild the application against Userspace RCU 0.11+. - - Rebuild the application with -fpic. + - Rebuild the application with `-fpic`. - Upgrade Userspace RCU to 0.13+ without installing 0.11 nor 0.12.