X-Git-Url: https://git.liburcu.org/?p=urcu.git;a=blobdiff_plain;f=README.md;h=a8318c823cca7dd026c284ce1521d95df731e7a1;hp=2b89ffa0af9f35469f7839568706829a20a6d3ac;hb=HEAD;hpb=afb6113ffba9d494ec90d773aed3e83acd299473 diff --git a/README.md b/README.md index 2b89ffa..d868ac4 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ + + Userspace RCU Implementation ============================ @@ -38,7 +44,7 @@ Architectures supported Currently, the following architectures are supported: - x86 (i386, i486, i586, i686) - - amd64 / x86_64 + - amd64 / x86\_64 - PowerPC 32/64 - S390, S390x - ARM 32/64 @@ -51,56 +57,56 @@ Currently, the following architectures are supported: - hppa/PA-RISC - m68k - RISC-V + - LoongArch 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 - - MacOSX amd64 + - MacOS amd64/arm64 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 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: +Toolchain support +----------------- + +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 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 + See - 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. + . - Linux aarch64 depends on GCC 5.1 or better because prior versions perform unsafe access to deallocated stack. Clang version 3.0 (based on LLVM 3.0) is supported. -Building on MacOS X (Darwin) requires a work-around for processor -detection: +Glibc >= 2.4 should work but the older version we test against is +currently 2.17. - - 32-bit: - ./configure --build=i686-apple-darwin11 - - - 64-bit: - - ./configure --build=x86_64-apple-darwin11 +Build system +------------ For developers using the Git tree: @@ -111,7 +117,7 @@ compile the git repository tree : - GNU autotools (automake >=1.12, autoconf >=2.69) (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/) + (for more information, go to ) 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 @@ -165,11 +171,10 @@ There are multiple flavors of liburcu available: - `memb`, - `qsbr`, - `mb`, - - `signal`, - `bp`. -The API members start with the prefix "urcu__", where - is the chosen flavor name. +The API members start with the prefix `urcu__`, where +`` is the chosen flavor name. ### Usage of `liburcu-memb` @@ -181,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,15 +215,6 @@ and reader sides. This results in faster grace-period detection, but results in slower reads. -### Usage of `liburcu-signal` - - 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`. - - ### Usage of `liburcu-bp` 1. `#include ` @@ -256,11 +252,19 @@ 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` - Follow instructions for either `liburcu-memb`, `liburcu-qsbr`, - `liburcu-mb`, `liburcu-signal`, or `liburcu-bp` above. + `liburcu-mb`, or `liburcu-bp` above. The `liburcu-defer` functionality is pulled into each of those library modules. - Provides `urcu__defer_rcu()` primitive to enqueue delayed @@ -279,7 +283,7 @@ Its API is currently experimental. It may change in future library releases. ### Usage of `urcu-call-rcu` - Follow instructions for either `liburcu-memb`, `liburcu-qsbr`, - `liburcu-mb`, `liburcu-signal`, or `liburcu-bp` above. + `liburcu-mb`, or `liburcu-bp` above. The `urcu-call-rcu` functionality is pulled into each of those library modules. - Provides the `urcu__call_rcu()` primitive to enqueue delayed @@ -297,13 +301,6 @@ Its API is currently experimental. It may change in future library releases. ### Being careful with signals -The `liburcu-signal` 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)`. - Read-side critical sections are allowed in a signal handler, except those setup with `sigaltstack(2)`, with `liburcu-memb` and `liburcu-mb`. Be careful, however, to disable these signals @@ -387,11 +384,12 @@ By default the library is configured with internal debugging self-checks disabled. For always-on debugging self-checks: - ./configure --enable-rcu-debug + + ./configure --enable-rcu-debug For fine grained enabling of debugging self-checks, build -userspace-rcu with DEBUG_RCU defined and compile dependent -applications with DEBUG_RCU defined when necessary. +userspace-rcu with `DEBUG_RCU` defined and compile dependent +applications with `DEBUG_RCU` defined when necessary. Warning: Enabling this feature result in a performance penalty. @@ -418,7 +416,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. @@ -426,19 +424,51 @@ 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 ------------ In addition to the usual `make check` target, Userspace RCU features -`make regtest` and `make bench` targets: +`make regtest`, `make short_bench` and `make long_bench` targets: - `make check`: short tests, meant to be run when rebuilding or porting Userspace RCU. - `make regtest`: long (many hours) test, meant to be run when modifying Userspace RCU or porting it to a new architecture or operating system. - - `make bench`: long (many hours) benchmarks. + - `make short_bench`: short benchmarks, 3 seconds per test. + - `make long_bench`: long (many hours) benchmarks, 30 seconds per test. + + +Known issues +------------ + +There is an application vs library compatibility issue between +applications built using Userspace RCU 0.10 headers linked against +Userspace RCU 0.11 or 0.12 shared objects. The problem occurs as +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. + + - The Userspace RCU 0.10 library shared objects are updated to 0.11 + or 0.12 without rebuilding the application. + + - The application will hang, typically when RCU grace period + (synchronize_rcu) is invoked. + +Some possible work-arounds for this are: + + - Rebuild the application against Userspace RCU 0.11+. + + - Rebuild the application with `-fpic`. + + - Upgrade Userspace RCU to 0.13+ without installing 0.11 nor 0.12. Contacts @@ -446,3 +476,18 @@ Contacts You can contact the maintainers on the following mailing list: `lttng-dev@lists.lttng.org`. + +IRC channel: [#lttng](irc://irc.oftc.net/lttng) on the OFTC network + +Bug tracker: [Userspace RCU bug tracker](https://bugs.lttng.org/projects/urcu) + +Code review: [_userspace-rcu_ project](https://review.lttng.org/q/project:userspace-rcu) on LTTng Review + +Continuous integration: [Userspace RCU](https://ci.lttng.org/view/Liburcu/) on LTTng's CI + +GitHub mirror: [urcu/userspace-rcu](https://github.com/urcu/userspace-rcu) + +Patches are principally submitted and reviewed on [LTTng Review](https://review.lttng.org), +but may also be submitted to the [mailing list](mailto:lttng-dev@lists.lttng.org) +with the subject prefix `PATCH urcu` or by pull request on the +[GitHub mirror](https://github.com/urcu/userspace-rcu).