2 * Copyright (c) 2013, 2014 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_THREAD_H 1
22 #include <sys/types.h>
23 #include "ovs-atomic.h"
28 struct OVS_LOCKABLE ovs_mutex {
33 /* "struct ovs_mutex" initializer. */
34 #ifdef PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP
35 #define OVS_MUTEX_INITIALIZER { PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP, NULL }
37 #define OVS_MUTEX_INITIALIZER { PTHREAD_MUTEX_INITIALIZER, NULL }
40 #ifdef PTHREAD_ADAPTIVE_MUTEX_INITIALIZER_NP
41 #define OVS_ADAPTIVE_MUTEX_INITIALIZER \
42 { PTHREAD_ADAPTIVE_MUTEX_INITIALIZER_NP, NULL }
44 #define OVS_ADAPTIVE_MUTEX_INITIALIZER OVS_MUTEX_INITIALIZER
47 /* ovs_mutex functions analogous to pthread_mutex_*() functions.
49 * Most of these functions abort the process with an error message on any
50 * error. ovs_mutex_trylock() is an exception: it passes through a 0 or EBUSY
51 * return value to the caller and aborts on any other error. */
52 void ovs_mutex_init(const struct ovs_mutex *);
53 void ovs_mutex_init_recursive(const struct ovs_mutex *);
54 void ovs_mutex_init_adaptive(const struct ovs_mutex *);
55 void ovs_mutex_destroy(const struct ovs_mutex *);
56 void ovs_mutex_unlock(const struct ovs_mutex *mutex) OVS_RELEASES(mutex);
57 void ovs_mutex_lock_at(const struct ovs_mutex *mutex, const char *where)
59 #define ovs_mutex_lock(mutex) \
60 ovs_mutex_lock_at(mutex, SOURCE_LOCATOR)
62 int ovs_mutex_trylock_at(const struct ovs_mutex *mutex, const char *where)
63 OVS_TRY_LOCK(0, mutex);
64 #define ovs_mutex_trylock(mutex) \
65 ovs_mutex_trylock_at(mutex, SOURCE_LOCATOR)
67 void ovs_mutex_cond_wait(pthread_cond_t *, const struct ovs_mutex *);
69 /* Wrappers for pthread_mutex_*() that abort the process on any error.
70 * This is still needed when ovs-atomic-pthreads.h is used. */
71 void xpthread_mutex_lock(pthread_mutex_t *mutex);
72 void xpthread_mutex_unlock(pthread_mutex_t *mutex);
74 /* Wrappers for pthread_mutexattr_*() that abort the process on any error. */
75 void xpthread_mutexattr_init(pthread_mutexattr_t *);
76 void xpthread_mutexattr_destroy(pthread_mutexattr_t *);
77 void xpthread_mutexattr_settype(pthread_mutexattr_t *, int type);
78 void xpthread_mutexattr_gettype(pthread_mutexattr_t *, int *typep);
80 /* Read-write lock. */
81 struct OVS_LOCKABLE ovs_rwlock {
82 pthread_rwlock_t lock;
87 #define OVS_RWLOCK_INITIALIZER { PTHREAD_RWLOCK_INITIALIZER, NULL }
89 /* ovs_rwlock functions analogous to pthread_rwlock_*() functions.
91 * Most of these functions abort the process with an error message on any
92 * error. The "trylock" functions are exception: they pass through a 0 or
93 * EBUSY return value to the caller and abort on any other error. */
94 void ovs_rwlock_init(const struct ovs_rwlock *);
95 void ovs_rwlock_destroy(const struct ovs_rwlock *);
96 void ovs_rwlock_unlock(const struct ovs_rwlock *rwlock) OVS_RELEASES(rwlock);
98 void ovs_rwlock_wrlock_at(const struct ovs_rwlock *rwlock, const char *where)
99 OVS_ACQ_WRLOCK(rwlock);
100 #define ovs_rwlock_wrlock(rwlock) \
101 ovs_rwlock_wrlock_at(rwlock, SOURCE_LOCATOR)
103 int ovs_rwlock_trywrlock_at(const struct ovs_rwlock *rwlock, const char *where)
104 OVS_TRY_WRLOCK(0, rwlock);
105 #define ovs_rwlock_trywrlock(rwlock) \
106 ovs_rwlock_trywrlock_at(rwlock, SOURCE_LOCATOR)
108 void ovs_rwlock_rdlock_at(const struct ovs_rwlock *rwlock, const char *where)
109 OVS_ACQ_RDLOCK(rwlock);
110 #define ovs_rwlock_rdlock(rwlock) \
111 ovs_rwlock_rdlock_at(rwlock, SOURCE_LOCATOR)
113 int ovs_rwlock_tryrdlock_at(const struct ovs_rwlock *rwlock, const char *where)
114 OVS_TRY_RDLOCK(0, rwlock);
115 #define ovs_rwlock_tryrdlock(rwlock) \
116 ovs_rwlock_tryrdlock_at(rwlock, SOURCE_LOCATOR)
118 /* Wrappers for xpthread_cond_*() that abort the process on any error.
120 * Use ovs_mutex_cond_wait() to wait for a condition. */
121 void xpthread_cond_init(pthread_cond_t *, pthread_condattr_t *);
122 void xpthread_cond_destroy(pthread_cond_t *);
123 void xpthread_cond_signal(pthread_cond_t *);
124 void xpthread_cond_broadcast(pthread_cond_t *);
127 /* Replace these functions by the macros already defined in the <pthread.h>
128 * annotations, because the macro definitions have correct semantics for the
129 * conditional acquisition that can't be captured in a function annotation.
130 * The difference in semantics from pthread_*() to xpthread_*() does not matter
131 * because sparse is not a compiler. */
132 #define xpthread_mutex_trylock pthread_mutex_trylock
133 #define xpthread_rwlock_tryrdlock pthread_rwlock_tryrdlock
134 #define xpthread_rwlock_trywrlock pthread_rwlock_trywrlock
137 void xpthread_key_create(pthread_key_t *, void (*destructor)(void *));
138 void xpthread_key_delete(pthread_key_t);
139 void xpthread_setspecific(pthread_key_t, const void *);
141 void xpthread_create(pthread_t *, pthread_attr_t *, void *(*)(void *), void *);
142 void xpthread_join(pthread_t, void **);
150 * Multiple forms of standard per-thread data exist, each with its own pluses
151 * and minuses. In general, if one of these forms is appropriate, then it's a
152 * good idea to use it:
154 * - POSIX per-thread data via pthread_key_t is portable to any pthreads
155 * implementation, and allows a destructor function to be defined. It
156 * only (directly) supports per-thread pointers, which are always
157 * initialized to NULL. It requires once-only allocation of a
158 * pthread_key_t value. It is relatively slow. Typically few
159 * "pthread_key_t"s are available (POSIX requires only at least 128,
160 * glibc supplies only 1024).
162 * - The thread_local feature newly defined in C11 <threads.h> works with
163 * any data type and initializer, and it is fast. thread_local does not
164 * require once-only initialization like pthread_key_t. C11 does not
165 * define what happens if one attempts to access a thread_local object
166 * from a thread other than the one to which that object belongs. There
167 * is no provision to call a user-specified destructor when a thread
168 * ends. Typical implementations allow for an arbitrary amount of
169 * thread_local storage, but statically allocated only.
171 * - The __thread keyword is a GCC extension similar to thread_local but
172 * with a longer history. __thread is not portable to every GCC version
173 * or environment. __thread does not restrict the use of a thread-local
174 * object outside its own thread.
176 * Here's a handy summary:
178 * pthread_key_t thread_local __thread
179 * ------------- ------------ -------------
180 * portability high low medium
181 * speed low high high
182 * supports destructors? yes no no
183 * needs key allocation? yes no no
184 * arbitrary initializer? no yes yes
185 * cross-thread access? yes no yes
186 * amount available? few arbitrary arbitrary
187 * dynamically allocated? yes no no
193 * OVS provides some extensions and wrappers:
195 * - In a situation where the performance of thread_local or __thread is
196 * desirable, but portability is required, DEFINE_STATIC_PER_THREAD_DATA
197 * and DECLARE_EXTERN_PER_THREAD_DATA/DEFINE_EXTERN_PER_THREAD_DATA may
198 * be appropriate (see below).
200 * - DEFINE_PER_THREAD_MALLOCED_DATA can be convenient for simple
201 * per-thread malloc()'d buffers.
203 * - struct ovs_tsd provides an alternative to pthread_key_t that isn't
204 * limited to a small number of keys.
207 /* For static data, use this macro in a source file:
209 * DEFINE_STATIC_PER_THREAD_DATA(TYPE, NAME, INITIALIZER).
211 * For global data, "declare" the data in the header and "define" it in
212 * the source file, with:
214 * DECLARE_EXTERN_PER_THREAD_DATA(TYPE, NAME).
215 * DEFINE_EXTERN_PER_THREAD_DATA(NAME, INITIALIZER).
217 * One should prefer to use POSIX per-thread data, via pthread_key_t, when its
218 * performance is acceptable, because of its portability (see the table above).
219 * This macro is an alternatives that takes advantage of thread_local (and
220 * __thread), for its performance, when it is available, and falls back to
221 * POSIX per-thread data otherwise.
223 * Defines per-thread variable NAME with the given TYPE, initialized to
224 * INITIALIZER (which must be valid as an initializer for a variable with
227 * The public interface to the variable is:
229 * TYPE *NAME_get(void)
230 * TYPE *NAME_get_unsafe(void)
232 * Returns the address of this thread's instance of NAME.
234 * Use NAME_get() in a context where this might be the first use of the
235 * per-thread variable in the program. Use NAME_get_unsafe(), which
236 * avoids a conditional test and is thus slightly faster, in a context
237 * where one knows that NAME_get() has already been called previously.
239 * There is no "NAME_set()" (or "NAME_set_unsafe()") function. To set the
240 * value of the per-thread variable, dereference the pointer returned by
241 * TYPE_get() or TYPE_get_unsafe(), e.g. *TYPE_get() = 0.
243 #if HAVE_THREAD_LOCAL || HAVE___THREAD
245 #if HAVE_THREAD_LOCAL
248 #define thread_local __thread
253 #define DEFINE_STATIC_PER_THREAD_DATA(TYPE, NAME, ...) \
254 typedef TYPE NAME##_type; \
256 static NAME##_type * \
257 NAME##_get_unsafe(void) \
259 static thread_local NAME##_type var = __VA_ARGS__; \
263 static NAME##_type * \
266 return NAME##_get_unsafe(); \
268 #define DECLARE_EXTERN_PER_THREAD_DATA(TYPE, NAME) \
269 typedef TYPE NAME##_type; \
270 extern thread_local NAME##_type NAME##_var; \
272 static inline NAME##_type * \
273 NAME##_get_unsafe(void) \
275 return &NAME##_var; \
278 static inline NAME##_type * \
281 return NAME##_get_unsafe(); \
283 #define DEFINE_EXTERN_PER_THREAD_DATA(NAME, ...) \
284 thread_local NAME##_type NAME##_var = __VA_ARGS__;
285 #else /* no C implementation support for thread-local storage */
286 #define DEFINE_STATIC_PER_THREAD_DATA(TYPE, NAME, ...) \
287 typedef TYPE NAME##_type; \
288 static pthread_key_t NAME##_key; \
290 static NAME##_type * \
291 NAME##_get_unsafe(void) \
293 return pthread_getspecific(NAME##_key); \
297 NAME##_once_init(void) \
299 if (pthread_key_create(&NAME##_key, free)) { \
304 static NAME##_type * \
307 static pthread_once_t once = PTHREAD_ONCE_INIT; \
308 NAME##_type *value; \
310 pthread_once(&once, NAME##_once_init); \
311 value = NAME##_get_unsafe(); \
313 static const NAME##_type initial_value = __VA_ARGS__; \
315 value = malloc(sizeof *value); \
316 if (value == NULL) { \
319 *value = initial_value; \
320 xpthread_setspecific(NAME##_key, value); \
324 #define DECLARE_EXTERN_PER_THREAD_DATA(TYPE, NAME) \
325 typedef TYPE NAME##_type; \
326 static pthread_key_t NAME##_key; \
328 static inline NAME##_type * \
329 NAME##_get_unsafe(void) \
331 return pthread_getspecific(NAME##_key); \
334 NAME##_type *NAME##_get(void);
335 #define DEFINE_EXTERN_PER_THREAD_DATA(NAME, ...) \
337 NAME##_once_init(void) \
339 if (pthread_key_create(&NAME##_key, free)) { \
347 static pthread_once_t once = PTHREAD_ONCE_INIT; \
348 NAME##_type *value; \
350 pthread_once(&once, NAME##_once_init); \
351 value = NAME##_get_unsafe(); \
353 static const NAME##_type initial_value = __VA_ARGS__; \
355 value = malloc(sizeof *value); \
356 if (value == NULL) { \
359 *value = initial_value; \
360 xpthread_setspecific(NAME##_key, value); \
366 /* DEFINE_PER_THREAD_MALLOCED_DATA(TYPE, NAME).
368 * This is a simple wrapper around POSIX per-thread data primitives. It
369 * defines per-thread variable NAME with the given TYPE, which must be a
370 * pointer type. In each thread, the per-thread variable is initialized to
371 * NULL. When a thread terminates, the variable is freed with free().
373 * The public interface to the variable is:
375 * TYPE NAME_get(void)
376 * TYPE NAME_get_unsafe(void)
378 * Returns the value of per-thread variable NAME in this thread.
380 * Use NAME_get() in a context where this might be the first use of the
381 * per-thread variable in the program. Use NAME_get_unsafe(), which
382 * avoids a conditional test and is thus slightly faster, in a context
383 * where one knows that NAME_get() has already been called previously.
385 * TYPE NAME_set(TYPE new_value)
386 * TYPE NAME_set_unsafe(TYPE new_value)
388 * Sets the value of per-thread variable NAME to 'new_value' in this
389 * thread, and returns its previous value.
391 * Use NAME_set() in a context where this might be the first use of the
392 * per-thread variable in the program. Use NAME_set_unsafe(), which
393 * avoids a conditional test and is thus slightly faster, in a context
394 * where one knows that NAME_set() has already been called previously.
396 #define DEFINE_PER_THREAD_MALLOCED_DATA(TYPE, NAME) \
397 static pthread_key_t NAME##_key; \
400 NAME##_once_init(void) \
402 if (pthread_key_create(&NAME##_key, free)) { \
410 static pthread_once_t once = PTHREAD_ONCE_INIT; \
411 pthread_once(&once, NAME##_once_init); \
415 NAME##_get_unsafe(void) \
417 return pthread_getspecific(NAME##_key); \
420 static OVS_UNUSED TYPE \
424 return NAME##_get_unsafe(); \
428 NAME##_set_unsafe(TYPE value) \
430 TYPE old_value = NAME##_get_unsafe(); \
431 xpthread_setspecific(NAME##_key, value); \
435 static OVS_UNUSED TYPE \
436 NAME##_set(TYPE value) \
439 return NAME##_set_unsafe(value); \
442 /* Dynamically allocated thread-specific data with lots of slots.
444 * pthread_key_t can provide as few as 128 pieces of thread-specific data (even
445 * glibc is limited to 1,024). Thus, one must be careful to allocate only a
446 * few keys globally. One cannot, for example, allocate a key for every
447 * instance of a data structure if there might be an arbitrary number of those
450 * This API is similar to the pthread one (simply search and replace pthread_
451 * by ovsthread_) but it a much larger limit that can be raised if necessary
452 * (by recompiling). Thus, one may more freely use this form of
453 * thread-specific data.
455 * ovsthread_key_t also differs from pthread_key_t in the following ways:
457 * - Destructors must not access thread-specific data (via ovsthread_key).
459 * - The pthread_key_t API allows concurrently exiting threads to start
460 * executing the destructor after pthread_key_delete() returns. The
461 * ovsthread_key_t API guarantees that, when ovsthread_key_delete()
462 * returns, all destructors have returned and no new ones will start
465 typedef struct ovsthread_key *ovsthread_key_t;
467 void ovsthread_key_create(ovsthread_key_t *, void (*destructor)(void *));
468 void ovsthread_key_delete(ovsthread_key_t);
470 void ovsthread_setspecific(ovsthread_key_t, const void *);
471 void *ovsthread_getspecific(ovsthread_key_t);
473 /* Convenient once-only execution.
479 * POSIX provides pthread_once_t and pthread_once() as primitives for running a
480 * set of code only once per process execution. They are used like this:
482 * static void run_once(void) { ...initialization... }
483 * static pthread_once_t once = PTHREAD_ONCE_INIT;
485 * pthread_once(&once, run_once);
487 * pthread_once() does not allow passing any parameters to the initialization
488 * function, which is often inconvenient, because it means that the function
489 * can only access data declared at file scope.
495 * Use ovsthread_once, like this, instead:
497 * static struct ovsthread_once once = OVSTHREAD_ONCE_INITIALIZER;
499 * if (ovsthread_once_start(&once)) {
500 * ...initialization...
501 * ovsthread_once_done(&once);
505 struct ovsthread_once {
507 struct ovs_mutex mutex;
510 #define OVSTHREAD_ONCE_INITIALIZER \
512 ATOMIC_VAR_INIT(false), \
513 OVS_MUTEX_INITIALIZER, \
516 static inline bool ovsthread_once_start(struct ovsthread_once *once)
517 OVS_TRY_LOCK(true, once->mutex);
518 void ovsthread_once_done(struct ovsthread_once *once)
519 OVS_RELEASES(once->mutex);
521 bool ovsthread_once_start__(struct ovsthread_once *once)
522 OVS_TRY_LOCK(false, once->mutex);
525 ovsthread_once_is_done__(struct ovsthread_once *once)
529 atomic_read_explicit(&once->done, &done, memory_order_relaxed);
533 /* Returns true if this is the first call to ovsthread_once_start() for
534 * 'once'. In this case, the caller should perform whatever initialization
535 * actions it needs to do, then call ovsthread_once_done() for 'once'.
537 * Returns false if this is not the first call to ovsthread_once_start() for
538 * 'once'. In this case, the call will not return until after
539 * ovsthread_once_done() has been called. */
541 ovsthread_once_start(struct ovsthread_once *once)
543 return OVS_UNLIKELY(!ovsthread_once_is_done__(once)
544 && !ovsthread_once_start__(once));
549 * pthread_t isn't so nice for some purposes. Its size and representation are
550 * implementation dependent, which means that there is no way to hash it.
551 * This thread ID avoids the problem.
554 DECLARE_EXTERN_PER_THREAD_DATA(unsigned int, ovsthread_id);
556 /* Returns a per-thread identifier unique within the lifetime of the
558 static inline unsigned int
559 ovsthread_id_self(void)
561 return *ovsthread_id_get();
564 /* Simulated global counter.
566 * Incrementing such a counter is meant to be cheaper than incrementing a
567 * global counter protected by a lock. It is probably more expensive than
568 * incrementing a truly thread-local variable, but such a variable has no
569 * straightforward way to get the sum.
575 * Fully thread-safe. */
577 struct ovsthread_counter *ovsthread_counter_create(void);
578 void ovsthread_counter_destroy(struct ovsthread_counter *);
579 void ovsthread_counter_inc(struct ovsthread_counter *, unsigned long long int);
580 unsigned long long int ovsthread_counter_read(
581 const struct ovsthread_counter *);
583 void assert_single_threaded_at(const char *where);
584 #define assert_single_threaded() assert_single_threaded_at(SOURCE_LOCATOR)
586 pid_t xfork_at(const char *where);
587 #define xfork() xfork_at(SOURCE_LOCATOR)
589 void forbid_forking(const char *reason);
592 /* Useful functions related to threading. */
594 int count_cpu_cores(void);
596 #endif /* ovs-thread.h */