84b97166cef4c2ec81cdf61734eb6f2d1d5fe6b1
[urcu.git] / doc / uatomic-api.md
1 <!--
2 SPDX-FileCopyrightText: 2023 EfficiOS Inc.
3
4 SPDX-License-Identifier: CC-BY-4.0
5 -->
6
7 Userspace RCU Atomic Operations API
8 ===================================
9
10 by Mathieu Desnoyers and Paul E. McKenney
11
12 This document describes the `<urcu/uatomic.h>` API. Those are the atomic
13 operations provided by the Userspace RCU library. The general rule
14 regarding memory barriers is that only `uatomic_xchg()`,
15 `uatomic_cmpxchg()`, `uatomic_add_return()`, and `uatomic_sub_return()` imply
16 full memory barriers before and after the atomic operation. Other
17 primitives don't guarantee any memory barrier.
18
19 Only atomic operations performed on integers (`int` and `long`, signed
20 and unsigned) are supported on all architectures. Some architectures
21 also support 1-byte and 2-byte atomic operations. Those respectively
22 have `UATOMIC_HAS_ATOMIC_BYTE` and `UATOMIC_HAS_ATOMIC_SHORT` defined when
23 `uatomic.h` is included. An architecture trying to perform an atomic write
24 to a type size not supported by the architecture will trigger an illegal
25 instruction.
26
27 In the description below, `type` is a type that can be atomically
28 written to by the architecture. It needs to be at most word-sized, and
29 its alignment needs to greater or equal to its size.
30
31
32 API
33 ---
34
35 ```c
36 void uatomic_set(type *addr, type v);
37 ```
38
39 Atomically write `v` into `addr`. By "atomically", we mean that no
40 concurrent operation that reads from addr will see partial
41 effects of `uatomic_set()`.
42
43
44 ```c
45 type uatomic_read(type *addr);
46 ```
47
48 Atomically read `v` from `addr`. By "atomically", we mean that
49 `uatomic_read()` cannot see a partial effect of any concurrent
50 uatomic update.
51
52
53 ```c
54 type uatomic_cmpxchg(type *addr, type old, type new);
55 ```
56
57 An atomic read-modify-write operation that performs this
58 sequence of operations atomically: check if `addr` contains `old`.
59 If true, then replace the content of `addr` by `new`. Return the
60 value previously contained by `addr`. This function implies a full
61 memory barrier before and after the atomic operation.
62
63
64 ```c
65 type uatomic_xchg(type *addr, type new);
66 ```
67
68 An atomic read-modify-write operation that performs this sequence
69 of operations atomically: replace the content of `addr` by `new`,
70 and return the value previously contained by `addr`. This
71 function implies a full memory barrier before and after the atomic
72 operation.
73
74
75 ```c
76 type uatomic_add_return(type *addr, type v);
77 type uatomic_sub_return(type *addr, type v);
78 ```
79
80 An atomic read-modify-write operation that performs this
81 sequence of operations atomically: increment/decrement the
82 content of `addr` by `v`, and return the resulting value. This
83 function implies a full memory barrier before and after the atomic
84 operation.
85
86
87 ```c
88 void uatomic_and(type *addr, type mask);
89 void uatomic_or(type *addr, type mask);
90 ```
91
92 Atomically write the result of bitwise "and"/"or" between the
93 content of `addr` and `mask` into `addr`.
94
95 These operations do not necessarily imply memory barriers.
96 If memory barriers are needed, they may be provided by explicitly using
97 `cmm_smp_mb__before_uatomic_and()`, `cmm_smp_mb__after_uatomic_and()`,
98 `cmm_smp_mb__before_uatomic_or()`, and `cmm_smp_mb__after_uatomic_or()`.
99 These explicit barriers are no-ops on architectures in which the underlying
100 atomic instructions implicitly supply the needed memory barriers.
101
102
103 ```c
104 void uatomic_add(type *addr, type v);
105 void uatomic_sub(type *addr, type v);
106 ```
107
108 Atomically increment/decrement the content of `addr` by `v`.
109 These operations do not necessarily imply memory barriers.
110 If memory barriers are needed, they may be provided by
111 explicitly using `cmm_smp_mb__before_uatomic_add()`,
112 `cmm_smp_mb__after_uatomic_add()`, `cmm_smp_mb__before_uatomic_sub()`, and
113 `cmm_smp_mb__after_uatomic_sub()`. These explicit barriers are
114 no-ops on architectures in which the underlying atomic
115 instructions implicitly supply the needed memory barriers.
116
117
118 ```c
119 void uatomic_inc(type *addr);
120 void uatomic_dec(type *addr);
121 ```
122
123 Atomically increment/decrement the content of `addr` by 1.
124 These operations do not necessarily imply memory barriers.
125 If memory barriers are needed, they may be provided by
126 explicitly using `cmm_smp_mb__before_uatomic_inc()`,
127 `cmm_smp_mb__after_uatomic_inc()`, `cmm_smp_mb__before_uatomic_dec()`,
128 and `cmm_smp_mb__after_uatomic_dec()`. These explicit barriers are
129 no-ops on architectures in which the underlying atomic
130 instructions implicitly supply the needed memory barriers.
This page took 0.0318 seconds and 3 git commands to generate.