X-Git-Url: https://git.lttng.org/?p=urcu.git;a=blobdiff_plain;f=README.md;h=2fe14c3db756394d2cdf2c09ebe5e1b018c89324;hp=cd24cc53ba0f3887d08c467be033f2e6af6f661d;hb=HEAD;hpb=ed4c6ca597ff4211e1379a650403836fd59e9368 diff --git a/README.md b/README.md index cd24cc5..d868ac4 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ + + Userspace RCU Implementation ============================ @@ -51,12 +57,12 @@ 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 - MacOS amd64/arm64 @@ -65,18 +71,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 +104,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 @@ -160,7 +171,6 @@ There are multiple flavors of liburcu available: - `memb`, - `qsbr`, - `mb`, - - `signal`, - `bp`. The API members start with the prefix `urcu__`, where @@ -205,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 ` @@ -251,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 @@ -274,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 @@ -292,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 @@ -422,6 +424,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 ------------ @@ -470,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).