+<!--
+SPDX-FileCopyrightText: 2023 EfficiOS Inc.
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
Userspace RCU Implementation
============================
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
- 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
- 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
+ <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 <http://kerneltrap.org/node/7507>
- 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.
+ <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.
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
- 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 <http://www.gnu.org/software/autoconf/>)
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
- `memb`,
- `qsbr`,
- `mb`,
- - `signal`,
- `bp`.
-The API members start with the prefix "urcu_<flavor>_", where
-<flavor> is the chosen flavor name.
+The API members start with the prefix `urcu_<flavor>_`, where
+`<flavor>` is the chosen flavor name.
### Usage of `liburcu-memb`
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
results in slower reads.
-### Usage of `liburcu-signal`
-
- 1. `#include <urcu/urcu-signal.h>`
- 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 <urcu/urcu-bp.h>`
After, `urcu_<flavor>_synchronize_rcu()` must be called. When it
returns, the old values are not in usage anymore.
+As an alternative to `urcu_<flavor>_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_<flavor>_start_poll_synchronize_rcu()`
+to start the grace period polling, and then invoke
+`urcu_<flavor>_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_<flavor>_defer_rcu()` primitive to enqueue delayed
### 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_<flavor>_call_rcu()` primitive to enqueue delayed
### 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
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.
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.
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
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).
projects / urcu.git / blobdiff