lib/process, socket-util: Update necessary headers
[sliver-openvswitch.git] / lib / ovs-atomic.h
1 /*
2  * Copyright (c) 2013 Nicira, Inc.
3  *
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:
7  *
8  *     http://www.apache.org/licenses/LICENSE-2.0
9  *
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.
15  */
16
17 #ifndef OVS_ATOMIC_H
18 #define OVS_ATOMIC_H 1
19
20 /* Atomic operations.
21  *
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
26  * for atomics.
27  *
28  * This comment describes the common features of all the implementations.
29  *
30  *
31  * Types
32  * =====
33  *
34  * The following atomic types are supported as typedefs for atomic versions of
35  * the listed ordinary types:
36  *
37  *     ordinary type            atomic version
38  *     -------------------      ----------------------
39  *     bool                     atomic_bool
40  *
41  *     char                     atomic_char
42  *     signed char              atomic_schar
43  *     unsigned char            atomic_uchar
44  *
45  *     short                    atomic_short
46  *     unsigned short           atomic_ushort
47  *
48  *     int                      atomic_int
49  *     unsigned int             atomic_uint
50  *
51  *     long                     atomic_long
52  *     unsigned long            atomic_ulong
53  *
54  *     long long                atomic_llong
55  *     unsigned long long       atomic_ullong
56  *
57  *     size_t                   atomic_size_t
58  *     ptrdiff_t                atomic_ptrdiff_t
59  *
60  *     intmax_t                 atomic_intmax_t
61  *     uintmax_t                atomic_uintmax_t
62  *
63  *     intptr_t                 atomic_intptr_t
64  *     uintptr_t                atomic_uintptr_t
65  *
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     (*)
74  *
75  *     (*) Not specified by C11.
76  *
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.
81  *
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
84  * that.
85  *
86  *
87  * Life Cycle
88  * ==========
89  *
90  * To initialize an atomic variable at its point of definition, use
91  * ATOMIC_VAR_INIT:
92  *
93  *     static atomic_int ai = ATOMIC_VAR_INIT(123);
94  *
95  * To initialize an atomic variable in code, use atomic_init():
96  *
97  *     static atomic_int ai;
98  * ...
99  *     atomic_init(&ai, 123);
100  *
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
104  * atomic type):
105  *
106  *     void atomic_destroy(A *object);
107  *
108  *         Destroys 'object'.
109  *
110  *
111  * Barriers
112  * ========
113  *
114  * enum memory_order specifies the strictness of a memory barrier.  It has the
115  * following values:
116  *
117  *    memory_order_relaxed:
118  *
119  *        Compiler barrier only.  Does not imply any CPU memory ordering.
120  *
121  *    memory_order_acquire:
122  *
123  *        Memory accesses after an acquire barrier cannot be moved before the
124  *        barrier.  Memory accesses before an acquire barrier *can* be moved
125  *        after it.
126  *
127  *    memory_order_release:
128  *
129  *        Memory accesses before a release barrier cannot be moved after the
130  *        barrier.  Memory accesses after a release barrier *can* be moved
131  *        before it.
132  *
133  *    memory_order_acq_rel:
134  *
135  *        Memory accesses cannot be moved across an acquire-release barrier in
136  *        either direction.
137  *
138  *    memory_order_seq_cst:
139  *
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.
143  *
144  *    memory_order_consume:
145  *
146  *        A slight relaxation of memory_order_acquire.
147  *
148  * The following functions insert explicit barriers.  Most of the other atomic
149  * functions also include barriers.
150  *
151  *     void atomic_thread_fence(memory_order order);
152  *
153  *         Inserts a barrier of the specified type.
154  *
155  *         For memory_order_relaxed, this is a no-op.
156  *
157  *     void atomic_signal_fence(memory_order order);
158  *
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.
163  *
164  *
165  * Atomic Operations
166  * =================
167  *
168  * In this section, A is an atomic type and C is the corresponding non-atomic
169  * type.
170  *
171  * The "store" primitives match C11:
172  *
173  *     void atomic_store(A *object, C value);
174  *     void atomic_store_explicit(A *object, C value, memory_order);
175  *
176  *         Atomically stores 'value' into '*object', respecting the given
177  *         memory order (or memory_order_seq_cst for atomic_store()).
178  *
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:
182  *
183  *     void atomic_read(A *src, C *dst);
184  *     void atomic_read_explicit(A *src, C *dst, memory_order);
185  *
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()).
189  *
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);
200  *
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).
205  *
206  *         The results are similar to those that would be obtained with +=, -=,
207  *         |=, ^=, or |= on non-atomic types.
208  *
209  *
210  * atomic_flag
211  * ===========
212  *
213  * atomic_flag is a typedef for a type with two states, set and clear, that
214  * provides atomic test-and-set functionality.
215  *
216  *
217  * Life Cycle
218  * ----------
219  *
220  * ATOMIC_FLAG_INIT is an initializer for atomic_flag.  The initial state is
221  * "clear".
222  *
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:
228  *
229  *     void atomic_flag_init(volatile atomic_flag *object);
230  *
231  *         Initializes 'object'.  The initial state is "clear".
232  *
233  *     void atomic_flag_destroy(volatile atomic_flag *object);
234  *
235  *         Destroys 'object'.
236  *
237  *
238  * Operations
239  * ----------
240  *
241  * The following functions are available.
242  *
243  *     bool atomic_flag_test_and_set(atomic_flag *object)
244  *     bool atomic_flag_test_and_set_explicit(atomic_flag *object,
245  *                                            memory_order);
246  *
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).
250  *
251  *     void atomic_flag_clear(atomic_flag *object);
252  *     void atomic_flag_clear_explicit(atomic_flag *object, memory_order);
253  *
254  *         Atomically clears '*object', respecting the given memory order (or
255  *         memory_order_seq_cst for atomic_flag_clear()).
256  */
257
258 #include <limits.h>
259 #include <pthread.h>
260 #include <stdbool.h>
261 #include <stddef.h>
262 #include <stdint.h>
263 #include "compiler.h"
264 #include "util.h"
265
266 #define IN_OVS_ATOMIC_H
267     #if __CHECKER__
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"
278     #else
279         #include "ovs-atomic-pthreads.h"
280     #endif
281 #undef IN_OVS_ATOMIC_H
282
283 /* Reference count. */
284 struct ovs_refcount {
285     atomic_uint count;
286 };
287
288 /* Initializes 'refcount'.  The reference count is initially 1. */
289 static inline void
290 ovs_refcount_init(struct ovs_refcount *refcount)
291 {
292     atomic_init(&refcount->count, 1);
293 }
294
295 /* Destroys 'refcount'. */
296 static inline void
297 ovs_refcount_destroy(struct ovs_refcount *refcount)
298 {
299     atomic_destroy(&refcount->count);
300 }
301
302 /* Increments 'refcount'. */
303 static inline void
304 ovs_refcount_ref(struct ovs_refcount *refcount)
305 {
306     unsigned int old_refcount;
307
308     atomic_add(&refcount->count, 1, &old_refcount);
309     ovs_assert(old_refcount > 0);
310 }
311
312 /* Decrements 'refcount' and returns the previous reference count.  Often used
313  * in this form:
314  *
315  * if (ovs_refcount_unref(&object->ref_cnt) == 1) {
316  *     // ...uninitialize object...
317  *     free(object);
318  * }
319  */
320 static inline unsigned int
321 ovs_refcount_unref(struct ovs_refcount *refcount)
322 {
323     unsigned int old_refcount;
324
325     atomic_sub(&refcount->count, 1, &old_refcount);
326     ovs_assert(old_refcount > 0);
327     return old_refcount;
328 }
329
330 /* Reads and returns 'ref_count_''s current reference count.
331  *
332  * Rarely useful. */
333 static inline unsigned int
334 ovs_refcount_read(const struct ovs_refcount *refcount_)
335 {
336     struct ovs_refcount *refcount
337         = CONST_CAST(struct ovs_refcount *, refcount_);
338     unsigned int count;
339
340     atomic_read(&refcount->count, &count);
341     return count;
342 }
343
344 #endif /* ovs-atomic.h */