1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
|
.\" Copyright (c) 2011 Ed Schouten <ed@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd December 27, 2011
.Dt ATOMIC_VAR_INIT 3
.Os
.Sh NAME
.Nm ATOMIC_VAR_INIT ,
.Nm atomic_init ,
.Nm atomic_load ,
.Nm atomic_store ,
.Nm atomic_exchange ,
.Nm atomic_compare_exchange_strong ,
.Nm atomic_compare_exchange_weak ,
.Nm atomic_fetch_add ,
.Nm atomic_fetch_and ,
.Nm atomic_fetch_or ,
.Nm atomic_fetch_sub ,
.Nm atomic_fetch_xor ,
.Nm atomic_is_lock_free
.Nd type-generic atomic operations
.Sh SYNOPSIS
.In stdatomic.h
.Pp
_Atomic(T)
.Fa v
= ATOMIC_VAR_INIT(c);
.Ft void
.Fn atomic_init "_Atomic(T) *object" "T value"
.Ft T
.Fn atomic_load "_Atomic(T) *object"
.Ft T
.Fn atomic_load_explicit "_Atomic(T) *object" "memory_order order"
.Ft void
.Fn atomic_store "_Atomic(T) *object" "T desired"
.Ft void
.Fn atomic_store_explicit "_Atomic(T) *object" "T desired" "memory_order order"
.Ft T
.Fn atomic_exchange "_Atomic(T) *object" "T desired"
.Ft T
.Fn atomic_exchange_explicit "_Atomic(T) *object" "T desired" "memory_order order"
.Ft _Bool
.Fn atomic_compare_exchange_strong "_Atomic(T) *object" "T *expected" "T desired"
.Ft _Bool
.Fn atomic_compare_exchange_strong_explicit "_Atomic(T) *object" "T *expected" "T desired" "memory_order success" "memory_order failure"
.Ft _Bool
.Fn atomic_compare_exchange_weak "_Atomic(T) *object" "T *expected" "T desired"
.Ft _Bool
.Fn atomic_compare_exchange_weak_explicit "_Atomic(T) *object" "T *expected" "T desired" "memory_order success" "memory_order failure"
.Ft T
.Fn atomic_fetch_add "_Atomic(T) *object" "T operand"
.Ft T
.Fn atomic_fetch_add_explicit "_Atomic(T) *object" "T operand" "memory_order order"
.Ft T
.Fn atomic_fetch_and "_Atomic(T) *object" "T operand"
.Ft T
.Fn atomic_fetch_and_explicit "_Atomic(T) *object" "T operand" "memory_order order"
.Ft T
.Fn atomic_fetch_or "_Atomic(T) *object" "T operand"
.Ft T
.Fn atomic_fetch_or_explicit "_Atomic(T) *object" "T operand" "memory_order order"
.Ft T
.Fn atomic_fetch_sub "_Atomic(T) *object" "T operand"
.Ft T
.Fn atomic_fetch_sub_explicit "_Atomic(T) *object" "T operand" "memory_order order"
.Ft T
.Fn atomic_fetch_xor "_Atomic(T) *object" "T operand"
.Ft T
.Fn atomic_fetch_xor_explicit "_Atomic(T) *object" "T operand" "memory_order order"
.Ft _Bool
.Fn atomic_is_lock_free "const _Atomic(T) *object"
.Sh DESCRIPTION
The header
.In stdatomic.h
provides type-generic macros for atomic operations.
Atomic operations can be used by multithreaded programs to provide
shared variables between threads that in most cases may be modified
without acquiring locks.
.Pp
Atomic variables are declared using the
.Fn _Atomic
type specifier.
These variables are not type-compatible with their non-atomic
counterparts.
Depending on the compiler used, atomic variables may be opaque and can
therefore only be influenced using the macros described.
.Pp
The
.Fn atomic_init
macro initializes the atomic variable
.Fa object
with a
.Fa value .
Atomic variables can be initialized while being declared using
.Fn ATOMIC_VAR_INIT .
.Pp
The
.Fn atomic_load
macro returns the value of atomic variable
.Fa object .
The
.Fn atomic_store
macro sets the atomic variable
.Fa object
to its
.Fa desired
value.
.Pp
The
.Fn atomic_exchange
macro combines the behaviour of
.Fn atomic_load
and
.Fn atomic_store .
It sets the atomic variable
.Fa object
to its desired
.Fa value
and returs the original contents of the atomic variable.
.Pp
The
.Fn atomic_compare_exchange_strong
macro stores a
.Fa desired
value into atomic variable
.Fa object ,
only if the atomic variable is equal to its
.Fa expected
value.
Upon success, the macro returns
.Dv true .
Upon failure, the
.Fa desired
value is overwritten with the value of the atomic variable and
.Dv false
is returned.
The
.Fn atomic_compare_exchange_weak
macro is identical to
.Fn atomic_compare_exchange_strong ,
but is allowed to fail even if atomic variable
.Fa object
is equal to its
.Fa expected
value.
.Pp
The
.Fn atomic_fetch_add
macro adds the value
.Fa operand
to atomic variable
.Fa object
and returns the original contents of the atomic variable.
.Pp
The
.Fn atomic_fetch_and
macro applies the
.Em and
operator to atomic variable
.Fa object
and
.Fa operand
and stores the value into
.Fa object ,
while returning the original contents of the atomic variable.
.Pp
The
.Fn atomic_fetch_or
macro applies the
.Em or
operator to atomic variable
.Fa object
and
.Fa operand
and stores the value into
.Fa object ,
while returning the original contents of the atomic variable.
.Pp
The
.Fn atomic_fetch_sub
macro subtracts the value
.Fa operand
to atomic variable
.Fa object
and returns the original contents of the atomic variable.
.Pp
The
.Fn atomic_fetch_xor
macro applies the
.Em xor
operator to atomic variable
.Fa object
and
.Fa operand
and stores the value into
.Fa object ,
while returning the original contents of the atomic variable.
.Pp
The
.Fn atomic_is_lock_free
macro returns whether atomic variable
.Fa object
uses locks when using atomic operations.
.Sh BARRIERS
The atomic operations described previously are implemented in such a way
that they disallow both the compiler and the executing processor to
re-order any nearby memory operations across the atomic operation.
In certain cases this behaviour may cause suboptimal performance.
To mitigate this, every atomic operation has an
.Fn _explicit
version that allows the re-ordering to be configured.
.Pp
The
.Fa order
parameter of these
.Fn _explicit
macros can have one of the following values.
.Bl -tag -width memory_order_relaxed
.It Dv memory_order_relaxed
No operation orders memory.
.It Dv memory_order_consume
Perform consume operation.
.It Dv memory_order_acquire
Acquire fence.
.It Dv memory_order_release
Release fence.
.It Dv memory_order_acq_rel
Acquire and release fence.
.It Dv memory_order_seq_cst
Sequentially consistent acquire and release fence.
.El
.Pp
The previously described macros are identical to the
.Fn _explicit
macros, when
.Fa order
is
.Dv memory_order_seq_cst .
.Sh COMPILER SUPPORT
These atomic operations are typically implemented by the compiler, as
they must be implemented type-generically and must often use special
hardware instructions.
As this interface has not been adopted by most compilers yet, the
.In stdatomic.h
header implements these macros on top of existing compiler intrinsics to
provide forward compatibility.
.Pp
This means that certain aspects of the interface, such as support for
different barrier types may simply be ignored.
When using GCC, all atomic operations are executed as if they are using
.Dv memory_order_seq_cst .
.Pp
Instead of using the atomic operations provided by this interface,
.St -isoC-11
allows the atomic variables to be modified directly using built-in
language operators.
This behaviour cannot be emulated for older compilers.
To prevent unintended non-atomic access to these variables, this header
file places the atomic variable in a structure when using an older
compiler.
.Pp
When using GCC on architectures on which it lacks support for built-in
atomic intrinsics, these macros may emit function calls to fallback
routines.
These fallback routines are only implemented for 32-bits and 64-bits
datatypes, if supported by the CPU.
.Sh SEE ALSO
.Xr pthread 3 ,
.Xr atomic 9
.Sh STANDARDS
These macros attempt to conform to
.St -isoC-11 .
.Sh HISTORY
These macros appeared in
.Fx 10.0 .
.Sh AUTHORS
.An Ed Schouten Aq ed@FreeBSD.org ,
.An David Chisnall Aq theraven@FreeBSD.org
|