tests/common: Remove urcu-signal common test files

[userspace-rcu.git] / README.md

diff --git a/README.md b/README.md
index 8f19e18c2dd849b8868ad01fe0c6caba9c171fe5..58db299018deb07f36fbdd1bad863ed35f82b3e0 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
 ============================
 


@@ -55,8 +61,7 @@ Currently, the following architectures are supported:
 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 +70,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 +103,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


@@ -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


@@ -210,9 +220,10 @@ results in slower reads.
   1. `#include <urcu/urcu-signal.h>`
   2. Link the application with `-lurcu-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`.
-
+NOTE: The `liburcu-signal` flavor is *deprecated* and will be removed in the
+future. It is now identical to `liburcu-mb` at the exception of the symbols and
+public header files. It is therefore slower than previous versions. Users are
+encouraged to migrate to the `liburcu-memb` flavor.

 
 ### Usage of `liburcu-bp`
 
 
 ### Usage of `liburcu-bp`
 


@@ -251,6 +262,14 @@ 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`
 
 
 ### Usage of `liburcu-defer`
 


@@ -414,7 +433,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.


@@ -422,6 +441,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
 ------------


@@ -448,7 +471,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.


@@ -460,7 +483,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.