datapath: Fix kernel style issues.
[sliver-openvswitch.git] / lib / ovs-thread.h
1 /*
2  * Copyright (c) 2013, 2014 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_THREAD_H
18 #define OVS_THREAD_H 1
19
20 #include <pthread.h>
21 #include <stddef.h>
22 #include <sys/types.h>
23 #include "ovs-atomic.h"
24 #include "util.h"
25
26
27 /* Mutex. */
28 struct OVS_LOCKABLE ovs_mutex {
29     pthread_mutex_t lock;
30     const char *where;
31 };
32
33 /* "struct ovs_mutex" initializer. */
34 #ifdef PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP
35 #define OVS_MUTEX_INITIALIZER { PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP, NULL }
36 #else
37 #define OVS_MUTEX_INITIALIZER { PTHREAD_MUTEX_INITIALIZER, NULL }
38 #endif
39
40 /* ovs_mutex functions analogous to pthread_mutex_*() functions.
41  *
42  * Most of these functions abort the process with an error message on any
43  * error.  ovs_mutex_trylock() is an exception: it passes through a 0 or EBUSY
44  * return value to the caller and aborts on any other error. */
45 void ovs_mutex_init(const struct ovs_mutex *);
46 void ovs_mutex_init_recursive(const struct ovs_mutex *);
47 void ovs_mutex_destroy(const struct ovs_mutex *);
48 void ovs_mutex_unlock(const struct ovs_mutex *mutex) OVS_RELEASES(mutex);
49 void ovs_mutex_lock_at(const struct ovs_mutex *mutex, const char *where)
50     OVS_ACQUIRES(mutex);
51 #define ovs_mutex_lock(mutex) \
52         ovs_mutex_lock_at(mutex, SOURCE_LOCATOR)
53
54 int ovs_mutex_trylock_at(const struct ovs_mutex *mutex, const char *where)
55     OVS_TRY_LOCK(0, mutex);
56 #define ovs_mutex_trylock(mutex) \
57         ovs_mutex_trylock_at(mutex, SOURCE_LOCATOR)
58
59 void ovs_mutex_cond_wait(pthread_cond_t *, const struct ovs_mutex *);
60
61 /* Wrappers for pthread_mutex_*() that abort the process on any error.
62  * This is still needed when ovs-atomic-pthreads.h is used. */
63 void xpthread_mutex_lock(pthread_mutex_t *mutex);
64 void xpthread_mutex_unlock(pthread_mutex_t *mutex);
65
66 /* Wrappers for pthread_mutexattr_*() that abort the process on any error. */
67 void xpthread_mutexattr_init(pthread_mutexattr_t *);
68 void xpthread_mutexattr_destroy(pthread_mutexattr_t *);
69 void xpthread_mutexattr_settype(pthread_mutexattr_t *, int type);
70 void xpthread_mutexattr_gettype(pthread_mutexattr_t *, int *typep);
71
72 /* Read-write lock. */
73 struct OVS_LOCKABLE ovs_rwlock {
74     pthread_rwlock_t lock;
75     const char *where;
76 };
77
78 /* Initializer. */
79 #define OVS_RWLOCK_INITIALIZER { PTHREAD_RWLOCK_INITIALIZER, NULL }
80
81 /* ovs_rwlock functions analogous to pthread_rwlock_*() functions.
82  *
83  * Most of these functions abort the process with an error message on any
84  * error.  The "trylock" functions are exception: they pass through a 0 or
85  * EBUSY return value to the caller and abort on any other error. */
86 void ovs_rwlock_init(const struct ovs_rwlock *);
87 void ovs_rwlock_destroy(const struct ovs_rwlock *);
88 void ovs_rwlock_unlock(const struct ovs_rwlock *rwlock) OVS_RELEASES(rwlock);
89
90 void ovs_rwlock_wrlock_at(const struct ovs_rwlock *rwlock, const char *where)
91     OVS_ACQ_WRLOCK(rwlock);
92 #define ovs_rwlock_wrlock(rwlock) \
93         ovs_rwlock_wrlock_at(rwlock, SOURCE_LOCATOR)
94
95 int ovs_rwlock_trywrlock_at(const struct ovs_rwlock *rwlock, const char *where)
96     OVS_TRY_WRLOCK(0, rwlock);
97 #define ovs_rwlock_trywrlock(rwlock) \
98     ovs_rwlock_trywrlock_at(rwlock, SOURCE_LOCATOR)
99
100 void ovs_rwlock_rdlock_at(const struct ovs_rwlock *rwlock, const char *where)
101     OVS_ACQ_RDLOCK(rwlock);
102 #define ovs_rwlock_rdlock(rwlock) \
103         ovs_rwlock_rdlock_at(rwlock, SOURCE_LOCATOR)
104
105 int ovs_rwlock_tryrdlock_at(const struct ovs_rwlock *rwlock, const char *where)
106     OVS_TRY_RDLOCK(0, rwlock);
107 #define ovs_rwlock_tryrdlock(rwlock) \
108         ovs_rwlock_tryrdlock_at(rwlock, SOURCE_LOCATOR)
109
110 /* Wrappers for xpthread_cond_*() that abort the process on any error.
111  *
112  * Use ovs_mutex_cond_wait() to wait for a condition. */
113 void xpthread_cond_init(pthread_cond_t *, pthread_condattr_t *);
114 void xpthread_cond_destroy(pthread_cond_t *);
115 void xpthread_cond_signal(pthread_cond_t *);
116 void xpthread_cond_broadcast(pthread_cond_t *);
117
118 #ifdef __CHECKER__
119 /* Replace these functions by the macros already defined in the <pthread.h>
120  * annotations, because the macro definitions have correct semantics for the
121  * conditional acquisition that can't be captured in a function annotation.
122  * The difference in semantics from pthread_*() to xpthread_*() does not matter
123  * because sparse is not a compiler. */
124 #define xpthread_mutex_trylock pthread_mutex_trylock
125 #define xpthread_rwlock_tryrdlock pthread_rwlock_tryrdlock
126 #define xpthread_rwlock_trywrlock pthread_rwlock_trywrlock
127 #endif
128
129 void xpthread_key_create(pthread_key_t *, void (*destructor)(void *));
130 void xpthread_key_delete(pthread_key_t);
131 void xpthread_setspecific(pthread_key_t, const void *);
132
133 void xpthread_create(pthread_t *, pthread_attr_t *, void *(*)(void *), void *);
134 void xpthread_join(pthread_t, void **);
135 \f
136 /* Per-thread data.
137  *
138  *
139  * Standard Forms
140  * ==============
141  *
142  * Multiple forms of standard per-thread data exist, each with its own pluses
143  * and minuses.  In general, if one of these forms is appropriate, then it's a
144  * good idea to use it:
145  *
146  *     - POSIX per-thread data via pthread_key_t is portable to any pthreads
147  *       implementation, and allows a destructor function to be defined.  It
148  *       only (directly) supports per-thread pointers, which are always
149  *       initialized to NULL.  It requires once-only allocation of a
150  *       pthread_key_t value.  It is relatively slow.  Typically few
151  *       "pthread_key_t"s are available (POSIX requires only at least 128,
152  *       glibc supplies only 1024).
153  *
154  *     - The thread_local feature newly defined in C11 <threads.h> works with
155  *       any data type and initializer, and it is fast.  thread_local does not
156  *       require once-only initialization like pthread_key_t.  C11 does not
157  *       define what happens if one attempts to access a thread_local object
158  *       from a thread other than the one to which that object belongs.  There
159  *       is no provision to call a user-specified destructor when a thread
160  *       ends.  Typical implementations allow for an arbitrary amount of
161  *       thread_local storage, but statically allocated only.
162  *
163  *     - The __thread keyword is a GCC extension similar to thread_local but
164  *       with a longer history.  __thread is not portable to every GCC version
165  *       or environment.  __thread does not restrict the use of a thread-local
166  *       object outside its own thread.
167  *
168  * Here's a handy summary:
169  *
170  *                     pthread_key_t     thread_local       __thread
171  *                     -------------     ------------     -------------
172  * portability             high               low             medium
173  * speed                    low              high               high
174  * supports destructors?    yes                no                 no
175  * needs key allocation?    yes                no                 no
176  * arbitrary initializer?    no               yes                yes
177  * cross-thread access?     yes                no                yes
178  * amount available?        few            arbitrary         arbitrary
179  * dynamically allocated?   yes                no                 no
180  *
181  *
182  * Extensions
183  * ==========
184  *
185  * OVS provides some extensions and wrappers:
186  *
187  *     - In a situation where the performance of thread_local or __thread is
188  *       desirable, but portability is required, DEFINE_STATIC_PER_THREAD_DATA
189  *       and DECLARE_EXTERN_PER_THREAD_DATA/DEFINE_EXTERN_PER_THREAD_DATA may
190  *       be appropriate (see below).
191  *
192  *     - DEFINE_PER_THREAD_MALLOCED_DATA can be convenient for simple
193  *       per-thread malloc()'d buffers.
194  *
195  *     - struct ovs_tsd provides an alternative to pthread_key_t that isn't
196  *       limited to a small number of keys.
197  */
198
199 /* For static data, use this macro in a source file:
200  *
201  *    DEFINE_STATIC_PER_THREAD_DATA(TYPE, NAME, INITIALIZER).
202  *
203  * For global data, "declare" the data in the header and "define" it in
204  * the source file, with:
205  *
206  *    DECLARE_EXTERN_PER_THREAD_DATA(TYPE, NAME).
207  *    DEFINE_EXTERN_PER_THREAD_DATA(NAME, INITIALIZER).
208  *
209  * One should prefer to use POSIX per-thread data, via pthread_key_t, when its
210  * performance is acceptable, because of its portability (see the table above).
211  * This macro is an alternatives that takes advantage of thread_local (and
212  * __thread), for its performance, when it is available, and falls back to
213  * POSIX per-thread data otherwise.
214  *
215  * Defines per-thread variable NAME with the given TYPE, initialized to
216  * INITIALIZER (which must be valid as an initializer for a variable with
217  * static lifetime).
218  *
219  * The public interface to the variable is:
220  *
221  *    TYPE *NAME_get(void)
222  *    TYPE *NAME_get_unsafe(void)
223  *
224  *       Returns the address of this thread's instance of NAME.
225  *
226  *       Use NAME_get() in a context where this might be the first use of the
227  *       per-thread variable in the program.  Use NAME_get_unsafe(), which
228  *       avoids a conditional test and is thus slightly faster, in a context
229  *       where one knows that NAME_get() has already been called previously.
230  *
231  * There is no "NAME_set()" (or "NAME_set_unsafe()") function.  To set the
232  * value of the per-thread variable, dereference the pointer returned by
233  * TYPE_get() or TYPE_get_unsafe(), e.g. *TYPE_get() = 0.
234  */
235 #if HAVE_THREAD_LOCAL || HAVE___THREAD
236
237 #if HAVE_THREAD_LOCAL
238 #include <threads.h>
239 #elif HAVE___THREAD
240 #define thread_local __thread
241 #else
242 #error
243 #endif
244
245 #define DEFINE_STATIC_PER_THREAD_DATA(TYPE, NAME, ...)                  \
246     typedef TYPE NAME##_type;                                           \
247                                                                         \
248     static NAME##_type *                                                \
249     NAME##_get_unsafe(void)                                             \
250     {                                                                   \
251         static thread_local NAME##_type var = __VA_ARGS__;              \
252         return &var;                                                    \
253     }                                                                   \
254                                                                         \
255     static NAME##_type *                                                \
256     NAME##_get(void)                                                    \
257     {                                                                   \
258         return NAME##_get_unsafe();                                     \
259     }
260 #define DECLARE_EXTERN_PER_THREAD_DATA(TYPE, NAME)                      \
261     typedef TYPE NAME##_type;                                           \
262     extern thread_local NAME##_type NAME##_var;                         \
263                                                                         \
264     static inline NAME##_type *                                         \
265     NAME##_get_unsafe(void)                                             \
266     {                                                                   \
267         return &NAME##_var;                                             \
268     }                                                                   \
269                                                                         \
270     static inline NAME##_type *                                         \
271     NAME##_get(void)                                                    \
272     {                                                                   \
273         return NAME##_get_unsafe();                                     \
274     }
275 #define DEFINE_EXTERN_PER_THREAD_DATA(NAME, ...)         \
276     thread_local NAME##_type NAME##_var = __VA_ARGS__;
277 #else  /* no C implementation support for thread-local storage  */
278 #define DEFINE_STATIC_PER_THREAD_DATA(TYPE, NAME, ...)                  \
279     typedef TYPE NAME##_type;                                           \
280     static pthread_key_t NAME##_key;                                    \
281                                                                         \
282     static NAME##_type *                                                \
283     NAME##_get_unsafe(void)                                             \
284     {                                                                   \
285         return pthread_getspecific(NAME##_key);                         \
286     }                                                                   \
287                                                                         \
288     static void                                                         \
289     NAME##_once_init(void)                                              \
290     {                                                                   \
291         if (pthread_key_create(&NAME##_key, free)) {                    \
292             abort();                                                    \
293         }                                                               \
294     }                                                                   \
295                                                                         \
296     static NAME##_type *                                                \
297     NAME##_get(void)                                                    \
298     {                                                                   \
299         static pthread_once_t once = PTHREAD_ONCE_INIT;                 \
300         NAME##_type *value;                                             \
301                                                                         \
302         pthread_once(&once, NAME##_once_init);                          \
303         value = NAME##_get_unsafe();                                    \
304         if (!value) {                                                   \
305             static const NAME##_type initial_value = __VA_ARGS__;       \
306                                                                         \
307             value = malloc(sizeof *value);                              \
308             if (value == NULL) {                                        \
309                 out_of_memory();                                        \
310             }                                                           \
311             *value = initial_value;                                     \
312             xpthread_setspecific(NAME##_key, value);                    \
313         }                                                               \
314         return value;                                                   \
315     }
316 #define DECLARE_EXTERN_PER_THREAD_DATA(TYPE, NAME)                      \
317     typedef TYPE NAME##_type;                                           \
318     static pthread_key_t NAME##_key;                                    \
319                                                                         \
320     static inline NAME##_type *                                         \
321     NAME##_get_unsafe(void)                                             \
322     {                                                                   \
323         return pthread_getspecific(NAME##_key);                         \
324     }                                                                   \
325                                                                         \
326     NAME##_type *NAME##_get(void);
327 #define DEFINE_EXTERN_PER_THREAD_DATA(NAME, ...)                        \
328     static void                                                         \
329     NAME##_once_init(void)                                              \
330     {                                                                   \
331         if (pthread_key_create(&NAME##_key, free)) {                    \
332             abort();                                                    \
333         }                                                               \
334     }                                                                   \
335                                                                         \
336     NAME##_type *                                                       \
337     NAME##_get(void)                                                    \
338     {                                                                   \
339         static pthread_once_t once = PTHREAD_ONCE_INIT;                 \
340         NAME##_type *value;                                             \
341                                                                         \
342         pthread_once(&once, NAME##_once_init);                          \
343         value = NAME##_get_unsafe();                                    \
344         if (!value) {                                                   \
345             static const NAME##_type initial_value = __VA_ARGS__;       \
346                                                                         \
347             value = malloc(sizeof *value);                              \
348             if (value == NULL) {                                        \
349                 out_of_memory();                                        \
350             }                                                           \
351             *value = initial_value;                                     \
352             xpthread_setspecific(NAME##_key, value);                    \
353         }                                                               \
354         return value;                                                   \
355     }
356 #endif
357
358 /* DEFINE_PER_THREAD_MALLOCED_DATA(TYPE, NAME).
359  *
360  * This is a simple wrapper around POSIX per-thread data primitives.  It
361  * defines per-thread variable NAME with the given TYPE, which must be a
362  * pointer type.  In each thread, the per-thread variable is initialized to
363  * NULL.  When a thread terminates, the variable is freed with free().
364  *
365  * The public interface to the variable is:
366  *
367  *    TYPE NAME_get(void)
368  *    TYPE NAME_get_unsafe(void)
369  *
370  *       Returns the value of per-thread variable NAME in this thread.
371  *
372  *       Use NAME_get() in a context where this might be the first use of the
373  *       per-thread variable in the program.  Use NAME_get_unsafe(), which
374  *       avoids a conditional test and is thus slightly faster, in a context
375  *       where one knows that NAME_get() has already been called previously.
376  *
377  *    TYPE NAME_set(TYPE new_value)
378  *    TYPE NAME_set_unsafe(TYPE new_value)
379  *
380  *       Sets the value of per-thread variable NAME to 'new_value' in this
381  *       thread, and returns its previous value.
382  *
383  *       Use NAME_set() in a context where this might be the first use of the
384  *       per-thread variable in the program.  Use NAME_set_unsafe(), which
385  *       avoids a conditional test and is thus slightly faster, in a context
386  *       where one knows that NAME_set() has already been called previously.
387  */
388 #define DEFINE_PER_THREAD_MALLOCED_DATA(TYPE, NAME)     \
389     static pthread_key_t NAME##_key;                    \
390                                                         \
391     static void                                         \
392     NAME##_once_init(void)                              \
393     {                                                   \
394         if (pthread_key_create(&NAME##_key, free)) {    \
395             abort();                                    \
396         }                                               \
397     }                                                   \
398                                                         \
399     static void                                         \
400     NAME##_init(void)                                   \
401     {                                                   \
402         static pthread_once_t once = PTHREAD_ONCE_INIT; \
403         pthread_once(&once, NAME##_once_init);          \
404     }                                                   \
405                                                         \
406     static TYPE                                         \
407     NAME##_get_unsafe(void)                             \
408     {                                                   \
409         return pthread_getspecific(NAME##_key);         \
410     }                                                   \
411                                                         \
412     static OVS_UNUSED TYPE                              \
413     NAME##_get(void)                                    \
414     {                                                   \
415         NAME##_init();                                  \
416         return NAME##_get_unsafe();                     \
417     }                                                   \
418                                                         \
419     static TYPE                                         \
420     NAME##_set_unsafe(TYPE value)                       \
421     {                                                   \
422         TYPE old_value = NAME##_get_unsafe();           \
423         xpthread_setspecific(NAME##_key, value);        \
424         return old_value;                               \
425     }                                                   \
426                                                         \
427     static OVS_UNUSED TYPE                              \
428     NAME##_set(TYPE value)                              \
429     {                                                   \
430         NAME##_init();                                  \
431         return NAME##_set_unsafe(value);                \
432     }
433
434 /* Dynamically allocated thread-specific data with lots of slots.
435  *
436  * pthread_key_t can provide as few as 128 pieces of thread-specific data (even
437  * glibc is limited to 1,024).  Thus, one must be careful to allocate only a
438  * few keys globally.  One cannot, for example, allocate a key for every
439  * instance of a data structure if there might be an arbitrary number of those
440  * data structures.
441  *
442  * This API is similar to the pthread one (simply search and replace pthread_
443  * by ovsthread_) but it a much larger limit that can be raised if necessary
444  * (by recompiling).  Thus, one may more freely use this form of
445  * thread-specific data.
446  *
447  * Compared to pthread_key_t, ovsthread_key_t has the follow limitations:
448  *
449  *    - Destructors must not access thread-specific data (via ovsthread_key).
450  */
451 typedef struct ovsthread_key *ovsthread_key_t;
452
453 void ovsthread_key_create(ovsthread_key_t *, void (*destructor)(void *));
454 void ovsthread_key_delete(ovsthread_key_t);
455
456 void ovsthread_setspecific(ovsthread_key_t, const void *);
457 void *ovsthread_getspecific(ovsthread_key_t);
458 \f
459 /* Convenient once-only execution.
460  *
461  *
462  * Problem
463  * =======
464  *
465  * POSIX provides pthread_once_t and pthread_once() as primitives for running a
466  * set of code only once per process execution.  They are used like this:
467  *
468  *     static void run_once(void) { ...initialization... }
469  *     static pthread_once_t once = PTHREAD_ONCE_INIT;
470  * ...
471  *     pthread_once(&once, run_once);
472  *
473  * pthread_once() does not allow passing any parameters to the initialization
474  * function, which is often inconvenient, because it means that the function
475  * can only access data declared at file scope.
476  *
477  *
478  * Solution
479  * ========
480  *
481  * Use ovsthread_once, like this, instead:
482  *
483  *     static struct ovsthread_once once = OVSTHREAD_ONCE_INITIALIZER;
484  *
485  *     if (ovsthread_once_start(&once)) {
486  *         ...initialization...
487  *         ovsthread_once_done(&once);
488  *     }
489  */
490
491 struct ovsthread_once {
492     atomic_bool done;
493     struct ovs_mutex mutex;
494 };
495
496 #define OVSTHREAD_ONCE_INITIALIZER              \
497     {                                           \
498         ATOMIC_VAR_INIT(false),                 \
499         OVS_MUTEX_INITIALIZER,                  \
500     }
501
502 static inline bool ovsthread_once_start(struct ovsthread_once *once)
503     OVS_TRY_LOCK(true, once->mutex);
504 void ovsthread_once_done(struct ovsthread_once *once)
505     OVS_RELEASES(once->mutex);
506
507 bool ovsthread_once_start__(struct ovsthread_once *once)
508     OVS_TRY_LOCK(false, once->mutex);
509
510 static inline bool
511 ovsthread_once_is_done__(struct ovsthread_once *once)
512 {
513     bool done;
514
515     atomic_read_explicit(&once->done, &done, memory_order_relaxed);
516     return done;
517 }
518
519 /* Returns true if this is the first call to ovsthread_once_start() for
520  * 'once'.  In this case, the caller should perform whatever initialization
521  * actions it needs to do, then call ovsthread_once_done() for 'once'.
522  *
523  * Returns false if this is not the first call to ovsthread_once_start() for
524  * 'once'.  In this case, the call will not return until after
525  * ovsthread_once_done() has been called. */
526 static inline bool
527 ovsthread_once_start(struct ovsthread_once *once)
528 {
529     return OVS_UNLIKELY(!ovsthread_once_is_done__(once)
530                         && !ovsthread_once_start__(once));
531 }
532 \f
533 /* Thread ID.
534  *
535  * pthread_t isn't so nice for some purposes.  Its size and representation are
536  * implementation dependent, which means that there is no way to hash it.
537  * This thread ID avoids the problem.
538  */
539
540 DECLARE_EXTERN_PER_THREAD_DATA(unsigned int, ovsthread_id);
541
542 /* Returns a per-thread identifier unique within the lifetime of the
543  * process. */
544 static inline unsigned int
545 ovsthread_id_self(void)
546 {
547     return *ovsthread_id_get();
548 }
549 \f
550 /* Simulated global counter.
551  *
552  * Incrementing such a counter is meant to be cheaper than incrementing a
553  * global counter protected by a lock.  It is probably more expensive than
554  * incrementing a truly thread-local variable, but such a variable has no
555  * straightforward way to get the sum.
556  *
557  *
558  * Thread-safety
559  * =============
560  *
561  * Fully thread-safe. */
562
563 struct ovsthread_counter *ovsthread_counter_create(void);
564 void ovsthread_counter_destroy(struct ovsthread_counter *);
565 void ovsthread_counter_inc(struct ovsthread_counter *, unsigned long long int);
566 unsigned long long int ovsthread_counter_read(
567     const struct ovsthread_counter *);
568 \f
569 void assert_single_threaded_at(const char *where);
570 #define assert_single_threaded() assert_single_threaded_at(SOURCE_LOCATOR)
571
572 pid_t xfork_at(const char *where);
573 #define xfork() xfork_at(SOURCE_LOCATOR)
574
575 void forbid_forking(const char *reason);
576 bool may_fork(void);
577 \f
578 /* Useful functions related to threading. */
579
580 int count_cpu_cores(void);
581
582 #endif /* ovs-thread.h */