projects / urcu.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
uatomic/x86: Remove redundant memory barriers
[urcu.git] / README.md
diff --git a/README.md b/README.md
index cd24cc53ba0f3887d08c467be033f2e6af6f661d..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,18 +71,19 @@ 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 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
 
   - 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.
 
 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
@@ -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
@@ -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
@@ -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.
 
 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
 ------------
@@ -470,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.024276 seconds and 4 git commands to generate.