~lttng/urcu/trunk

« back to all changes in this revision

Viewing changes to README.md

  • Committer: Mathieu Desnoyers
  • Date: 2023-08-21 19:22:27 UTC
  • Revision ID: git-v1:aad674a9a583e09e854145f18c5d8854269dce8c
Complete removal of urcu-signal flavor

This commit completes removal of the urcu-signal flavor.

Users can migrate to liburcu-memb with a kernel implementing the
membarrier(2) system call to have similar read-side performance without
requiring use of a reserved signal, and with improved grace period
performance.

Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Change-Id: I75b9171e705b9b2ef4c8eeabe6164e5587816fb4

Show diffs side-by-side

added added

removed removed

Lines of Context:
170
170
  - `memb`,
171
171
  - `qsbr`,
172
172
  - `mb`,
173
 
  - `signal`,
174
173
  - `bp`.
175
174
 
176
175
The API members start with the prefix `urcu_<flavor>_`, where
215
214
results in slower reads.
216
215
 
217
216
 
218
 
### Usage of `liburcu-signal`
219
 
 
220
 
  1. `#include <urcu/urcu-signal.h>`
221
 
  2. Link the application with `-lurcu-signal`
222
 
 
223
 
NOTE: The `liburcu-signal` flavor is *deprecated* and will be removed in the
224
 
future. It is now identical to `liburcu-mb` at the exception of the symbols and
225
 
public header files. It is therefore slower than previous versions. Users are
226
 
encouraged to migrate to the `liburcu-memb` flavor.
227
 
 
228
217
### Usage of `liburcu-bp`
229
218
 
230
219
  1. `#include <urcu/urcu-bp.h>`
274
263
### Usage of `liburcu-defer`
275
264
 
276
265
  - Follow instructions for either `liburcu-memb`, `liburcu-qsbr`,
277
 
    `liburcu-mb`, `liburcu-signal`, or `liburcu-bp` above.
 
266
    `liburcu-mb`, or `liburcu-bp` above.
278
267
    The `liburcu-defer` functionality is pulled into each of
279
268
    those library modules.
280
269
  - Provides `urcu_<flavor>_defer_rcu()` primitive to enqueue delayed
293
282
### Usage of `urcu-call-rcu`
294
283
 
295
284
  - Follow instructions for either `liburcu-memb`, `liburcu-qsbr`,
296
 
    `liburcu-mb`, `liburcu-signal`, or `liburcu-bp` above.
 
285
    `liburcu-mb`, or `liburcu-bp` above.
297
286
    The `urcu-call-rcu` functionality is pulled into each of
298
287
    those library modules.
299
288
  - Provides the `urcu_<flavor>_call_rcu()` primitive to enqueue delayed
311
300
 
312
301
### Being careful with signals
313
302
 
314
 
The `liburcu-signal` library uses signals internally. The signal handler is
315
 
registered with the `SA_RESTART` flag. However, these signals may cause
316
 
some non-restartable system calls to fail with `errno = EINTR`. Care
317
 
should be taken to restart system calls manually if they fail with this
318
 
error. A list of non-restartable system calls may be found in
319
 
`signal(7)`.
320
 
 
321
303
Read-side critical sections are allowed in a signal handler,
322
304
except those setup with `sigaltstack(2)`, with `liburcu-memb` and
323
305
`liburcu-mb`. Be careful, however, to disable these signals