Branch data Line data Source code
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 "openvswitch/thread.h"
25 : : #include "util.h"
26 : :
27 : : struct seq;
28 : :
29 : : /* Poll-block()-able barrier similar to pthread_barrier_t. */
30 : : struct ovs_barrier {
31 : : uint32_t size; /* Number of threads to wait. */
32 : : atomic_count count; /* Number of threads already hit the barrier. */
33 : : struct seq *seq;
34 : : };
35 : :
36 : : /* Wrappers for pthread_mutex_*() that abort the process on any error.
37 : : * This is still needed when ovs-atomic-pthreads.h is used. */
38 : : void xpthread_mutex_lock(pthread_mutex_t *mutex);
39 : : void xpthread_mutex_unlock(pthread_mutex_t *mutex);
40 : :
41 : : /* Wrappers for pthread_mutexattr_*() that abort the process on any error. */
42 : : void xpthread_mutexattr_init(pthread_mutexattr_t *);
43 : : void xpthread_mutexattr_destroy(pthread_mutexattr_t *);
44 : : void xpthread_mutexattr_settype(pthread_mutexattr_t *, int type);
45 : : void xpthread_mutexattr_gettype(pthread_mutexattr_t *, int *typep);
46 : :
47 : : /* Read-write lock.
48 : : *
49 : : * An ovs_rwlock does not support recursive readers, because POSIX allows
50 : : * taking the reader lock recursively to deadlock when a thread is waiting on
51 : : * the write-lock. (NetBSD does deadlock.) glibc rwlocks in their default
52 : : * configuration do not deadlock, but ovs_rwlock_init() initializes rwlocks as
53 : : * non-recursive (which will deadlock) for two reasons:
54 : : *
55 : : * - glibc only provides fairness to writers in this mode.
56 : : *
57 : : * - It's better to find bugs in the primary Open vSwitch target rather
58 : : * than exposing them only to porters. */
59 : : struct OVS_LOCKABLE ovs_rwlock {
60 : : pthread_rwlock_t lock;
61 : : const char *where; /* NULL if and only if uninitialized. */
62 : : };
63 : :
64 : : /* Initializer. */
65 : : #ifdef PTHREAD_RWLOCK_WRITER_NONRECURSIVE_INITIALIZER_NP
66 : : #define OVS_RWLOCK_INITIALIZER \
67 : : { PTHREAD_RWLOCK_WRITER_NONRECURSIVE_INITIALIZER_NP, "<unlocked>" }
68 : : #else
69 : : #define OVS_RWLOCK_INITIALIZER { PTHREAD_RWLOCK_INITIALIZER, "<unlocked>" }
70 : : #endif
71 : :
72 : : /* ovs_rwlock functions analogous to pthread_rwlock_*() functions.
73 : : *
74 : : * Most of these functions abort the process with an error message on any
75 : : * error. The "trylock" functions are exception: they pass through a 0 or
76 : : * EBUSY return value to the caller and abort on any other error. */
77 : : void ovs_rwlock_init(const struct ovs_rwlock *);
78 : : void ovs_rwlock_destroy(const struct ovs_rwlock *);
79 : : void ovs_rwlock_unlock(const struct ovs_rwlock *rwlock) OVS_RELEASES(rwlock);
80 : :
81 : : /* Wrappers for pthread_rwlockattr_*() that abort the process on any error. */
82 : : void xpthread_rwlockattr_init(pthread_rwlockattr_t *);
83 : : void xpthread_rwlockattr_destroy(pthread_rwlockattr_t *);
84 : : #ifdef PTHREAD_RWLOCK_WRITER_NONRECURSIVE_INITIALIZER_NP
85 : : void xpthread_rwlockattr_setkind_np(pthread_rwlockattr_t *, int kind);
86 : : #endif
87 : :
88 : : void ovs_rwlock_wrlock_at(const struct ovs_rwlock *rwlock, const char *where)
89 : : OVS_ACQ_WRLOCK(rwlock);
90 : : #define ovs_rwlock_wrlock(rwlock) \
91 : : ovs_rwlock_wrlock_at(rwlock, OVS_SOURCE_LOCATOR)
92 : :
93 : : int ovs_rwlock_trywrlock_at(const struct ovs_rwlock *rwlock, const char *where)
94 : : OVS_TRY_WRLOCK(0, rwlock);
95 : : #define ovs_rwlock_trywrlock(rwlock) \
96 : : ovs_rwlock_trywrlock_at(rwlock, OVS_SOURCE_LOCATOR)
97 : :
98 : : void ovs_rwlock_rdlock_at(const struct ovs_rwlock *rwlock, const char *where)
99 : : OVS_ACQ_RDLOCK(rwlock);
100 : : #define ovs_rwlock_rdlock(rwlock) \
101 : : ovs_rwlock_rdlock_at(rwlock, OVS_SOURCE_LOCATOR)
102 : :
103 : : int ovs_rwlock_tryrdlock_at(const struct ovs_rwlock *rwlock, const char *where)
104 : : OVS_TRY_RDLOCK(0, rwlock);
105 : : #define ovs_rwlock_tryrdlock(rwlock) \
106 : : ovs_rwlock_tryrdlock_at(rwlock, OVS_SOURCE_LOCATOR)
107 : :
108 : : /* ovs_barrier functions analogous to pthread_barrier_*() functions. */
109 : : void ovs_barrier_init(struct ovs_barrier *, uint32_t count);
110 : : void ovs_barrier_destroy(struct ovs_barrier *);
111 : : void ovs_barrier_block(struct ovs_barrier *);
112 : :
113 : : /* Wrappers for xpthread_cond_*() that abort the process on any error.
114 : : *
115 : : * Use ovs_mutex_cond_wait() to wait for a condition. */
116 : : void xpthread_cond_init(pthread_cond_t *, pthread_condattr_t *);
117 : : void xpthread_cond_destroy(pthread_cond_t *);
118 : : void xpthread_cond_signal(pthread_cond_t *);
119 : : void xpthread_cond_broadcast(pthread_cond_t *);
120 : :
121 : : void xpthread_key_create(pthread_key_t *, void (*destructor)(void *));
122 : : void xpthread_key_delete(pthread_key_t);
123 : : void xpthread_setspecific(pthread_key_t, const void *);
124 : :
125 : : #ifndef _WIN32
126 : : void xpthread_sigmask(int, const sigset_t *, sigset_t *);
127 : : #endif
128 : :
129 : : pthread_t ovs_thread_create(const char *name, void *(*)(void *), void *);
130 : : void xpthread_join(pthread_t, void **);
131 : :
132 : : /* Per-thread data.
133 : : *
134 : : *
135 : : * Standard Forms
136 : : * ==============
137 : : *
138 : : * Multiple forms of standard per-thread data exist, each with its own pluses
139 : : * and minuses. In general, if one of these forms is appropriate, then it's a
140 : : * good idea to use it:
141 : : *
142 : : * - POSIX per-thread data via pthread_key_t is portable to any pthreads
143 : : * implementation, and allows a destructor function to be defined. It
144 : : * only (directly) supports per-thread pointers, which are always
145 : : * initialized to NULL. It requires once-only allocation of a
146 : : * pthread_key_t value. It is relatively slow. Typically few
147 : : * "pthread_key_t"s are available (POSIX requires only at least 128,
148 : : * glibc supplies only 1024).
149 : : *
150 : : * - The thread_local feature newly defined in C11 <threads.h> works with
151 : : * any data type and initializer, and it is fast. thread_local does not
152 : : * require once-only initialization like pthread_key_t. C11 does not
153 : : * define what happens if one attempts to access a thread_local object
154 : : * from a thread other than the one to which that object belongs. There
155 : : * is no provision to call a user-specified destructor when a thread
156 : : * ends. Typical implementations allow for an arbitrary amount of
157 : : * thread_local storage, but statically allocated only.
158 : : *
159 : : * - The __thread keyword is a GCC extension similar to thread_local but
160 : : * with a longer history. __thread is not portable to every GCC version
161 : : * or environment. __thread does not restrict the use of a thread-local
162 : : * object outside its own thread.
163 : : *
164 : : * Here's a handy summary:
165 : : *
166 : : * pthread_key_t thread_local __thread
167 : : * ------------- ------------ -------------
168 : : * portability high low medium
169 : : * speed low high high
170 : : * supports destructors? yes no no
171 : : * needs key allocation? yes no no
172 : : * arbitrary initializer? no yes yes
173 : : * cross-thread access? yes no yes
174 : : * amount available? few arbitrary arbitrary
175 : : * dynamically allocated? yes no no
176 : : *
177 : : *
178 : : * Extensions
179 : : * ==========
180 : : *
181 : : * OVS provides some extensions and wrappers:
182 : : *
183 : : * - In a situation where the performance of thread_local or __thread is
184 : : * desirable, but portability is required, DEFINE_STATIC_PER_THREAD_DATA
185 : : * and DECLARE_EXTERN_PER_THREAD_DATA/DEFINE_EXTERN_PER_THREAD_DATA may
186 : : * be appropriate (see below).
187 : : *
188 : : * - DEFINE_PER_THREAD_MALLOCED_DATA can be convenient for simple
189 : : * per-thread malloc()'d buffers.
190 : : *
191 : : * - struct ovs_tsd provides an alternative to pthread_key_t that isn't
192 : : * limited to a small number of keys.
193 : : */
194 : :
195 : : /* For static data, use this macro in a source file:
196 : : *
197 : : * DEFINE_STATIC_PER_THREAD_DATA(TYPE, NAME, INITIALIZER).
198 : : *
199 : : * For global data, "declare" the data in the header and "define" it in
200 : : * the source file, with:
201 : : *
202 : : * DECLARE_EXTERN_PER_THREAD_DATA(TYPE, NAME).
203 : : * DEFINE_EXTERN_PER_THREAD_DATA(NAME, INITIALIZER).
204 : : *
205 : : * One should prefer to use POSIX per-thread data, via pthread_key_t, when its
206 : : * performance is acceptable, because of its portability (see the table above).
207 : : * This macro is an alternatives that takes advantage of thread_local (and
208 : : * __thread), for its performance, when it is available, and falls back to
209 : : * POSIX per-thread data otherwise.
210 : : *
211 : : * Defines per-thread variable NAME with the given TYPE, initialized to
212 : : * INITIALIZER (which must be valid as an initializer for a variable with
213 : : * static lifetime).
214 : : *
215 : : * The public interface to the variable is:
216 : : *
217 : : * TYPE *NAME_get(void)
218 : : * TYPE *NAME_get_unsafe(void)
219 : : *
220 : : * Returns the address of this thread's instance of NAME.
221 : : *
222 : : * Use NAME_get() in a context where this might be the first use of the
223 : : * per-thread variable in the program. Use NAME_get_unsafe(), which
224 : : * avoids a conditional test and is thus slightly faster, in a context
225 : : * where one knows that NAME_get() has already been called previously.
226 : : *
227 : : * There is no "NAME_set()" (or "NAME_set_unsafe()") function. To set the
228 : : * value of the per-thread variable, dereference the pointer returned by
229 : : * TYPE_get() or TYPE_get_unsafe(), e.g. *TYPE_get() = 0.
230 : : */
231 : : #if HAVE_THREAD_LOCAL || HAVE___THREAD
232 : :
233 : : #if HAVE_THREAD_LOCAL
234 : : #include <threads.h>
235 : : #elif HAVE___THREAD
236 : : #define thread_local __thread
237 : : #else
238 : : #error
239 : : #endif
240 : :
241 : : #define DEFINE_STATIC_PER_THREAD_DATA(TYPE, NAME, ...) \
242 : : typedef TYPE NAME##_type; \
243 : : \
244 : : static NAME##_type * \
245 : : NAME##_get_unsafe(void) \
246 : : { \
247 : : static thread_local NAME##_type var = __VA_ARGS__; \
248 : : return &var; \
249 : : } \
250 : : \
251 : : static NAME##_type * \
252 : : NAME##_get(void) \
253 : : { \
254 : : return NAME##_get_unsafe(); \
255 : : }
256 : : #define DECLARE_EXTERN_PER_THREAD_DATA(TYPE, NAME) \
257 : : typedef TYPE NAME##_type; \
258 : : extern thread_local NAME##_type NAME##_var; \
259 : : \
260 : : static inline NAME##_type * \
261 : : NAME##_get_unsafe(void) \
262 : : { \
263 : : return &NAME##_var; \
264 : : } \
265 : : \
266 : : static inline NAME##_type * \
267 : : NAME##_get(void) \
268 : : { \
269 : : return NAME##_get_unsafe(); \
270 : : }
271 : : #define DEFINE_EXTERN_PER_THREAD_DATA(NAME, ...) \
272 : : thread_local NAME##_type NAME##_var = __VA_ARGS__;
273 : : #else /* no C implementation support for thread-local storage */
274 : : #define DEFINE_STATIC_PER_THREAD_DATA(TYPE, NAME, ...) \
275 : : typedef TYPE NAME##_type; \
276 : : static pthread_key_t NAME##_key; \
277 : : \
278 : : static NAME##_type * \
279 : : NAME##_get_unsafe(void) \
280 : : { \
281 : : return pthread_getspecific(NAME##_key); \
282 : : } \
283 : : \
284 : : static void \
285 : : NAME##_once_init(void) \
286 : : { \
287 : : if (pthread_key_create(&NAME##_key, free)) { \
288 : : abort(); \
289 : : } \
290 : : } \
291 : : \
292 : : static NAME##_type * \
293 : : NAME##_get(void) \
294 : : { \
295 : : static pthread_once_t once = PTHREAD_ONCE_INIT; \
296 : : NAME##_type *value; \
297 : : \
298 : : pthread_once(&once, NAME##_once_init); \
299 : : value = NAME##_get_unsafe(); \
300 : : if (!value) { \
301 : : static const NAME##_type initial_value = __VA_ARGS__; \
302 : : \
303 : : value = malloc(sizeof *value); \
304 : : if (value == NULL) { \
305 : : out_of_memory(); \
306 : : } \
307 : : *value = initial_value; \
308 : : xpthread_setspecific(NAME##_key, value); \
309 : : } \
310 : : return value; \
311 : : }
312 : : #define DECLARE_EXTERN_PER_THREAD_DATA(TYPE, NAME) \
313 : : typedef TYPE NAME##_type; \
314 : : static pthread_key_t NAME##_key; \
315 : : \
316 : : static inline NAME##_type * \
317 : : NAME##_get_unsafe(void) \
318 : : { \
319 : : return pthread_getspecific(NAME##_key); \
320 : : } \
321 : : \
322 : : NAME##_type *NAME##_get(void);
323 : : #define DEFINE_EXTERN_PER_THREAD_DATA(NAME, ...) \
324 : : static void \
325 : : NAME##_once_init(void) \
326 : : { \
327 : : if (pthread_key_create(&NAME##_key, free)) { \
328 : : abort(); \
329 : : } \
330 : : } \
331 : : \
332 : : NAME##_type * \
333 : : NAME##_get(void) \
334 : : { \
335 : : static pthread_once_t once = PTHREAD_ONCE_INIT; \
336 : : NAME##_type *value; \
337 : : \
338 : : pthread_once(&once, NAME##_once_init); \
339 : : value = NAME##_get_unsafe(); \
340 : : if (!value) { \
341 : : static const NAME##_type initial_value = __VA_ARGS__; \
342 : : \
343 : : value = malloc(sizeof *value); \
344 : : if (value == NULL) { \
345 : : out_of_memory(); \
346 : : } \
347 : : *value = initial_value; \
348 : : xpthread_setspecific(NAME##_key, value); \
349 : : } \
350 : : return value; \
351 : : }
352 : : #endif
353 : :
354 : : /* DEFINE_PER_THREAD_MALLOCED_DATA(TYPE, NAME).
355 : : *
356 : : * This is a simple wrapper around POSIX per-thread data primitives. It
357 : : * defines per-thread variable NAME with the given TYPE, which must be a
358 : : * pointer type. In each thread, the per-thread variable is initialized to
359 : : * NULL. When a thread terminates, the variable is freed with free().
360 : : *
361 : : * The public interface to the variable is:
362 : : *
363 : : * TYPE NAME_get(void)
364 : : * TYPE NAME_get_unsafe(void)
365 : : *
366 : : * Returns the value of per-thread variable NAME in this thread.
367 : : *
368 : : * Use NAME_get() in a context where this might be the first use of the
369 : : * per-thread variable in the program. Use NAME_get_unsafe(), which
370 : : * avoids a conditional test and is thus slightly faster, in a context
371 : : * where one knows that NAME_get() has already been called previously.
372 : : *
373 : : * TYPE NAME_set(TYPE new_value)
374 : : * TYPE NAME_set_unsafe(TYPE new_value)
375 : : *
376 : : * Sets the value of per-thread variable NAME to 'new_value' in this
377 : : * thread, and returns its previous value.
378 : : *
379 : : * Use NAME_set() in a context where this might be the first use of the
380 : : * per-thread variable in the program. Use NAME_set_unsafe(), which
381 : : * avoids a conditional test and is thus slightly faster, in a context
382 : : * where one knows that NAME_set() has already been called previously.
383 : : */
384 : : #define DEFINE_PER_THREAD_MALLOCED_DATA(TYPE, NAME) \
385 : : static pthread_key_t NAME##_key; \
386 : : \
387 : : static void \
388 : : NAME##_once_init(void) \
389 : : { \
390 : : if (pthread_key_create(&NAME##_key, free)) { \
391 : : abort(); \
392 : : } \
393 : : } \
394 : : \
395 : : static void \
396 : : NAME##_init(void) \
397 : : { \
398 : : static pthread_once_t once = PTHREAD_ONCE_INIT; \
399 : : pthread_once(&once, NAME##_once_init); \
400 : : } \
401 : : \
402 : : static TYPE \
403 : : NAME##_get_unsafe(void) \
404 : : { \
405 : : return pthread_getspecific(NAME##_key); \
406 : : } \
407 : : \
408 : : static OVS_UNUSED TYPE \
409 : : NAME##_get(void) \
410 : : { \
411 : : NAME##_init(); \
412 : : return NAME##_get_unsafe(); \
413 : : } \
414 : : \
415 : : static TYPE \
416 : : NAME##_set_unsafe(TYPE value) \
417 : : { \
418 : : TYPE old_value = NAME##_get_unsafe(); \
419 : : xpthread_setspecific(NAME##_key, value); \
420 : : return old_value; \
421 : : } \
422 : : \
423 : : static OVS_UNUSED TYPE \
424 : : NAME##_set(TYPE value) \
425 : : { \
426 : : NAME##_init(); \
427 : : return NAME##_set_unsafe(value); \
428 : : }
429 : :
430 : : /* Dynamically allocated thread-specific data with lots of slots.
431 : : *
432 : : * pthread_key_t can provide as few as 128 pieces of thread-specific data (even
433 : : * glibc is limited to 1,024). Thus, one must be careful to allocate only a
434 : : * few keys globally. One cannot, for example, allocate a key for every
435 : : * instance of a data structure if there might be an arbitrary number of those
436 : : * data structures.
437 : : *
438 : : * This API is similar to the pthread one (simply search and replace pthread_
439 : : * by ovsthread_) but it a much larger limit that can be raised if necessary
440 : : * (by recompiling). Thus, one may more freely use this form of
441 : : * thread-specific data.
442 : : *
443 : : * ovsthread_key_t also differs from pthread_key_t in the following ways:
444 : : *
445 : : * - Destructors must not access thread-specific data (via ovsthread_key).
446 : : *
447 : : * - The pthread_key_t API allows concurrently exiting threads to start
448 : : * executing the destructor after pthread_key_delete() returns. The
449 : : * ovsthread_key_t API guarantees that, when ovsthread_key_delete()
450 : : * returns, all destructors have returned and no new ones will start
451 : : * execution.
452 : : */
453 : : typedef struct ovsthread_key *ovsthread_key_t;
454 : :
455 : : void ovsthread_key_create(ovsthread_key_t *, void (*destructor)(void *));
456 : : void ovsthread_key_delete(ovsthread_key_t);
457 : :
458 : : void ovsthread_setspecific(ovsthread_key_t, const void *);
459 : : void *ovsthread_getspecific(ovsthread_key_t);
460 : :
461 : : /* Thread ID.
462 : : *
463 : : * pthread_t isn't so nice for some purposes. Its size and representation are
464 : : * implementation dependent, which means that there is no way to hash it.
465 : : * This thread ID avoids the problem.
466 : : */
467 : :
468 : 9101428 : DECLARE_EXTERN_PER_THREAD_DATA(unsigned int, ovsthread_id);
469 : :
470 : : /* Returns a per-thread identifier unique within the lifetime of the
471 : : * process. */
472 : : static inline unsigned int
473 : 2269574 : ovsthread_id_self(void)
474 : : {
475 : 2269574 : return *ovsthread_id_get();
476 : : }
477 : :
478 : : /* Simulated global counter.
479 : : *
480 : : * Incrementing such a counter is meant to be cheaper than incrementing a
481 : : * global counter protected by a lock. It is probably more expensive than
482 : : * incrementing a truly thread-local variable, but such a variable has no
483 : : * straightforward way to get the sum.
484 : : *
485 : : *
486 : : * Thread-safety
487 : : * =============
488 : : *
489 : : * Fully thread-safe. */
490 : :
491 : : struct ovsthread_stats {
492 : : struct ovs_mutex mutex;
493 : : void *volatile buckets[16];
494 : : };
495 : :
496 : : void ovsthread_stats_init(struct ovsthread_stats *);
497 : : void ovsthread_stats_destroy(struct ovsthread_stats *);
498 : :
499 : : void *ovsthread_stats_bucket_get(struct ovsthread_stats *,
500 : : void *(*new_bucket)(void));
501 : :
502 : : #define OVSTHREAD_STATS_FOR_EACH_BUCKET(BUCKET, IDX, STATS) \
503 : : for ((IDX) = ovs_thread_stats_next_bucket(STATS, 0); \
504 : : ((IDX) < ARRAY_SIZE((STATS)->buckets) \
505 : : ? ((BUCKET) = (STATS)->buckets[IDX], true) \
506 : : : false); \
507 : : (IDX) = ovs_thread_stats_next_bucket(STATS, (IDX) + 1))
508 : : size_t ovs_thread_stats_next_bucket(const struct ovsthread_stats *, size_t);
509 : :
510 : : bool single_threaded(void);
511 : :
512 : : void assert_single_threaded_at(const char *where);
513 : : #define assert_single_threaded() assert_single_threaded_at(OVS_SOURCE_LOCATOR)
514 : :
515 : : #ifndef _WIN32
516 : : pid_t xfork_at(const char *where);
517 : : #define xfork() xfork_at(OVS_SOURCE_LOCATOR)
518 : : #endif
519 : :
520 : : void forbid_forking(const char *reason);
521 : : bool may_fork(void);
522 : :
523 : : /* Useful functions related to threading. */
524 : :
525 : : int count_cpu_cores(void);
526 : : bool thread_is_pmd(void);
527 : :
528 : : #endif /* ovs-thread.h */
|
