2 * Copyright (c) 2013 Nicira, Inc.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at:
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 #define OVS_ATOMIC_H 1
22 * This library implements atomic operations with an API based on the one
23 * defined in C11. It includes multiple implementations for compilers and
24 * libraries with varying degrees of built-in support for C11, including a
25 * fallback implementation for systems that have pthreads but no other support
28 * This comment describes the common features of all the implementations.
34 * The following atomic types are supported as typedefs for atomic versions of
35 * the listed ordinary types:
37 * ordinary type atomic version
38 * ------------------- ----------------------
42 * signed char atomic_schar
43 * unsigned char atomic_uchar
46 * unsigned short atomic_ushort
49 * unsigned int atomic_uint
52 * unsigned long atomic_ulong
54 * long long atomic_llong
55 * unsigned long long atomic_ullong
57 * size_t atomic_size_t
58 * ptrdiff_t atomic_ptrdiff_t
60 * intmax_t atomic_intmax_t
61 * uintmax_t atomic_uintmax_t
63 * intptr_t atomic_intptr_t
64 * uintptr_t atomic_uintptr_t
66 * uint8_t atomic_uint8_t (*)
67 * uint16_t atomic_uint16_t (*)
68 * uint32_t atomic_uint32_t (*)
69 * int8_t atomic_int8_t (*)
70 * int16_t atomic_int16_t (*)
71 * int32_t atomic_int32_t (*)
72 * uint64_t atomic_uint64_t (*)
73 * int64_t atomic_int64_t (*)
75 * (*) Not specified by C11.
77 * The atomic version of a type doesn't necessarily have the same size or
78 * representation as the ordinary version; for example, atomic_int might be a
79 * typedef for a struct that also includes a mutex. The range of an atomic
80 * type does match the range of the corresponding ordinary type.
82 * C11 says that one may use the _Atomic keyword in place of the typedef name,
83 * e.g. "_Atomic int" instead of "atomic_int". This library doesn't support
90 * To initialize an atomic variable at its point of definition, use
93 * static atomic_int ai = ATOMIC_VAR_INIT(123);
95 * To initialize an atomic variable in code, use atomic_init():
97 * static atomic_int ai;
99 * atomic_init(&ai, 123);
101 * C11 does not hav an destruction function for atomic types, but some
102 * implementations of the OVS atomics do need them. Thus, the following
103 * function is provided for destroying non-static atomic objects (A is any
106 * void atomic_destroy(A *object);
114 * enum memory_order specifies the strictness of a memory barrier. It has the
117 * memory_order_relaxed:
119 * Compiler barrier only. Does not imply any CPU memory ordering.
121 * memory_order_acquire:
123 * Memory accesses after an acquire barrier cannot be moved before the
124 * barrier. Memory accesses before an acquire barrier *can* be moved
127 * memory_order_release:
129 * Memory accesses before a release barrier cannot be moved after the
130 * barrier. Memory accesses after a release barrier *can* be moved
133 * memory_order_acq_rel:
135 * Memory accesses cannot be moved across an acquire-release barrier in
138 * memory_order_seq_cst:
140 * Prevents movement of memory accesses like an acquire-release barrier,
141 * but whereas acquire-release synchronizes cooperating threads,
142 * sequential-consistency synchronizes the whole system.
144 * memory_order_consume:
146 * A slight relaxation of memory_order_acquire.
148 * The following functions insert explicit barriers. Most of the other atomic
149 * functions also include barriers.
151 * void atomic_thread_fence(memory_order order);
153 * Inserts a barrier of the specified type.
155 * For memory_order_relaxed, this is a no-op.
157 * void atomic_signal_fence(memory_order order);
159 * Inserts a barrier of the specified type, but only with respect to
160 * signal handlers in the same thread as the barrier. This is
161 * basically a compiler optimization barrier, except for
162 * memory_order_relaxed, which is a no-op.
168 * In this section, A is an atomic type and C is the corresponding non-atomic
171 * The "store" primitives match C11:
173 * void atomic_store(A *object, C value);
174 * void atomic_store_explicit(A *object, C value, memory_order);
176 * Atomically stores 'value' into '*object', respecting the given
177 * memory order (or memory_order_seq_cst for atomic_store()).
179 * The following primitives differ from the C11 ones (and have different names)
180 * because there does not appear to be a way to implement the standard
181 * primitives in standard C:
183 * void atomic_read(A *src, C *dst);
184 * void atomic_read_explicit(A *src, C *dst, memory_order);
186 * Atomically loads a value from 'src', writing the value read into
187 * '*dst', respecting the given memory order (or memory_order_seq_cst
188 * for atomic_read()).
190 * void atomic_add(A *rmw, C arg, C *orig);
191 * void atomic_sub(A *rmw, C arg, C *orig);
192 * void atomic_or(A *rmw, C arg, C *orig);
193 * void atomic_xor(A *rmw, C arg, C *orig);
194 * void atomic_and(A *rmw, C arg, C *orig);
195 * void atomic_add_explicit(A *rmw, C arg, C *orig, memory_order);
196 * void atomic_sub_explicit(A *rmw, C arg, C *orig, memory_order);
197 * void atomic_or_explicit(A *rmw, C arg, C *orig, memory_order);
198 * void atomic_xor_explicit(A *rmw, C arg, C *orig, memory_order);
199 * void atomic_and_explicit(A *rmw, C arg, C *orig, memory_order);
201 * Atomically applies the given operation, with 'arg' as the second
202 * operand, to '*rmw', and stores the original value of '*rmw' into
203 * '*orig', respecting the given memory order (or memory_order_seq_cst
204 * if none is specified).
206 * The results are similar to those that would be obtained with +=, -=,
207 * |=, ^=, or |= on non-atomic types.
213 * atomic_flag is a typedef for a type with two states, set and clear, that
214 * provides atomic test-and-set functionality.
220 * ATOMIC_FLAG_INIT is an initializer for atomic_flag. The initial state is
223 * C11 does not have an initialization or destruction function for atomic_flag,
224 * because implementations should not need one (one may simply
225 * atomic_flag_clear() an uninitialized atomic_flag), but some implementations
226 * of the OVS atomics do need them. Thus, the following two functions are
227 * provided for initializing and destroying non-static atomic_flags:
229 * void atomic_flag_init(volatile atomic_flag *object);
231 * Initializes 'object'. The initial state is "clear".
233 * void atomic_flag_destroy(volatile atomic_flag *object);
241 * The following functions are available.
243 * bool atomic_flag_test_and_set(atomic_flag *object)
244 * bool atomic_flag_test_and_set_explicit(atomic_flag *object,
247 * Atomically sets '*object', respsecting the given memory order (or
248 * memory_order_seq_cst for atomic_flag_test_and_set()). Returns the
249 * previous value of the flag (false for clear, true for set).
251 * void atomic_flag_clear(atomic_flag *object);
252 * void atomic_flag_clear_explicit(atomic_flag *object, memory_order);
254 * Atomically clears '*object', respecting the given memory order (or
255 * memory_order_seq_cst for atomic_flag_clear()).
263 #include "compiler.h"
266 #define IN_OVS_ATOMIC_H
268 /* sparse doesn't understand some GCC extensions we use. */
269 #include "ovs-atomic-pthreads.h"
270 #elif HAVE_STDATOMIC_H
271 #include "ovs-atomic-c11.h"
272 #elif __has_extension(c_atomic)
273 #include "ovs-atomic-clang.h"
274 #elif __GNUC__ >= 4 && __GNUC_MINOR__ >= 7
275 #include "ovs-atomic-gcc4.7+.h"
276 #elif HAVE_GCC4_ATOMICS
277 #include "ovs-atomic-gcc4+.h"
279 #include "ovs-atomic-pthreads.h"
281 #undef IN_OVS_ATOMIC_H
283 /* Reference count. */
284 struct ovs_refcount {
288 /* Initializes 'refcount'. The reference count is initially 1. */
290 ovs_refcount_init(struct ovs_refcount *refcount)
292 atomic_init(&refcount->count, 1);
295 /* Destroys 'refcount'. */
297 ovs_refcount_destroy(struct ovs_refcount *refcount)
299 atomic_destroy(&refcount->count);
302 /* Increments 'refcount'. */
304 ovs_refcount_ref(struct ovs_refcount *refcount)
306 unsigned int old_refcount;
308 atomic_add(&refcount->count, 1, &old_refcount);
309 ovs_assert(old_refcount > 0);
312 /* Decrements 'refcount' and returns the previous reference count. Often used
315 * if (ovs_refcount_unref(&object->ref_cnt) == 1) {
316 * // ...uninitialize object...
320 static inline unsigned int
321 ovs_refcount_unref(struct ovs_refcount *refcount)
323 unsigned int old_refcount;
325 atomic_sub(&refcount->count, 1, &old_refcount);
326 ovs_assert(old_refcount > 0);
330 /* Reads and returns 'ref_count_''s current reference count.
333 static inline unsigned int
334 ovs_refcount_read(const struct ovs_refcount *refcount_)
336 struct ovs_refcount *refcount
337 = CONST_CAST(struct ovs_refcount *, refcount_);
340 atomic_read(&refcount->count, &count);
344 #endif /* ovs-atomic.h */