examples/performance-thread/pthread_shim/pthread_shim.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2015 Intel Corporation
   3  */
   4
   5 #ifndef _PTHREAD_SHIM_H_
   6 #define _PTHREAD_SHIM_H_
   7
   8 #include <rte_lcore.h>
   9
  10 /*
  11  * This pthread shim is an example that demonstrates how legacy code
  12  * that makes use of POSIX pthread services can make use of lthreads
  13  * with reduced porting effort.
  14  *
  15  * N.B. The example is not a complete implementation, only a subset of
  16  * pthread APIs sufficient to demonstrate the principle of operation
  17  * are implemented.
  18  *
  19  * In general pthread attribute objects do not have equivalent functions
  20  * in lthreads, and are ignored.
  21  *
  22  * There is one exception and that is the use of attr to specify a
  23  * core affinity in calls to pthread_create.
  24  *
  25  * The shim operates as follows:-
  26  *
  27  * On initialisation a constructor function uses dlsym to obtain and
  28  * save the loaded address of the full set of pthread APIs that will
  29  * be overridden.
  30  *
  31  * For each function there is a stub provided that will invoke either
  32  * the genuine pthread library function saved saved by the constructor,
  33  * or else the corresponding equivalent lthread function.
  34  *
  35  * The stub functions are implemented in pthread_shim.c
  36  *
  37  * The stub will take care of adapting parameters, and any police
  38  * any constraints where lthread functionality differs.
  39  *
  40  * The initial thread must always be a pure lthread.
  41  *
  42  * The decision whether to invoke the real library function or the lthread
  43  * function is controlled by a per pthread flag that can be switched
  44  * on of off by the pthread_override_set() API described below. Typcially
  45  * this should be done as the first action of the initial lthread.
  46  *
  47  * N.B In general it would be poor practice to revert to invoke a real
  48  * pthread function when running as an lthread, since these may block and
  49  * effectively stall the lthread scheduler.
  50  *
  51  */
  52
  53
  54 /*
  55  * An exiting lthread must not terminate the pthread it is running in
  56  * since this would mean terminating the lthread scheduler.
  57  * We override pthread_exit() with a macro because it is typically declared with
  58  * __attribute__((noreturn))
  59  */
  60 void pthread_exit_override(void *v);
  61
  62 #define pthread_exit(v) do { \
  63         pthread_exit_override((v));     \
  64         return NULL;    \
  65 } while (0)
  66
  67 /*
  68  * Enable/Disable pthread override
  69  * state
  70  * 0 disable
  71  * 1 enable
  72  */
  73 void pthread_override_set(int state);
  74
  75
  76 /*
  77  * Return pthread override state
  78  * return
  79  * 0 disable
  80  * 1 enable
  81  */
  82 int pthread_override_get(void);
  83
  84
  85 #endif /* _PTHREAD_SHIM_H_ */