projects / urcu.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
fix: handle EINTR correctly in get_cpu_mask_from_sysfs
[urcu.git] / README.md
diff --git a/README.md b/README.md
index f75af605db88de89e8ac6bd3d26358ff1cf5766c..d868ac491c50152662c25c4ffe48723f32f15cf7 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,3 +1,9 @@
+<!--
+SPDX-FileCopyrightText: 2023 EfficiOS Inc.
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
 Userspace RCU Implementation
 ============================
 
 Userspace RCU Implementation
 ============================
 
@@ -51,12 +57,12 @@ Currently, the following architectures are supported:
   - hppa/PA-RISC
   - m68k
   - RISC-V
   - hppa/PA-RISC
   - m68k
   - RISC-V
+  - LoongArch
 
 Tested on:
 
   - Linux all architectures
 
 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
 
   - Cygwin i386/amd64
   - MacOS amd64/arm64
 
@@ -65,30 +71,31 @@ Should also work on:
   - Android
   - NetBSD 5
   - OpenBSD
   - Android
   - NetBSD 5
   - OpenBSD
-  - Darwin
+  - Solaris
 
 (more testing needed before claiming support for these OS).
 
 
 (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 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.
 
 
-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:
+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:
 
   - 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.
   - 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:
   - 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.
 
   - Linux aarch64 depends on GCC 5.1 or better because prior versions
     perform unsafe access to deallocated stack.
 
@@ -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.
 
 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
 For developers using the Git tree:
 
 This source tree is based on the autotools suite from GNU to simplify
@@ -106,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
   - 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
 
 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
@@ -160,7 +171,6 @@ There are multiple flavors of liburcu available:
   - `memb`,
   - `qsbr`,
   - `mb`,
   - `memb`,
   - `qsbr`,
   - `mb`,
-  - `signal`,
   - `bp`.
 
 The API members start with the prefix `urcu_<flavor>_`, where
   - `bp`.
 
 The API members start with the prefix `urcu_<flavor>_`, where
@@ -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
 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
 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
@@ -205,15 +215,6 @@ and reader sides. This results in faster grace-period detection, but
 results in slower reads.
 
 
 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>`
 ### Usage of `liburcu-bp`
 
   1. `#include <urcu/urcu-bp.h>`
@@ -251,11 +252,19 @@ protected pointer.
 After, `urcu_<flavor>_synchronize_rcu()` must be called. When it
 returns, the old values are not in usage anymore.
 
 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`,
 
 ### 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
     The `liburcu-defer` functionality is pulled into each of
     those library modules.
   - Provides `urcu_<flavor>_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`,
 ### 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
     The `urcu-call-rcu` functionality is pulled into each of
     those library modules.
   - Provides the `urcu_<flavor>_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
 
 
 ### 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
 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
@@ -382,7 +384,8 @@ By default the library is configured with internal debugging
 self-checks disabled.
 
 For always-on debugging self-checks:
 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
 
 For fine grained enabling of debugging self-checks, build
 userspace-rcu with `DEBUG_RCU` defined and compile dependent
@@ -413,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.
 
 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.
 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.
@@ -421,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.
 
 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
 ------------
 
 Make targets
 ------------
@@ -447,7 +454,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
 
   - 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.
 
   - The Userspace RCU 0.10 library shared objects are updated to 0.11
     or 0.12 without rebuilding the application.
@@ -459,7 +466,7 @@ Some possible work-arounds for this are:
 
   - Rebuild the application against Userspace RCU 0.11+.
 
 
   - 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.
 
 
   - Upgrade Userspace RCU to 0.13+ without installing 0.11 nor 0.12.
 
@@ -469,3 +476,18 @@ Contacts
 
 You can contact the maintainers on the following mailing list:
 `lttng-dev@lists.lttng.org`.
 
 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).
Userspace RCU (urcu) for Linux
This page took 0.025203 seconds and 4 git commands to generate.