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 "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 \f
 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 \f
 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 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 ovsthread_id_self(void)
 474 {
 475     return *ovsthread_id_get();
 476 }
 477 \f
 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 \f
 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 \f
 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 */