trace2/tr2_tls.h

   1 #ifndef TR2_TLS_H
   2 #define TR2_TLS_H
   3
   4 #include "trace2/tr2_ctr.h"
   5 #include "trace2/tr2_tmr.h"
   6
   7 /*
   8  * Notice: the term "TLS" refers to "thread-local storage" in the
   9  * Trace2 source files.  This usage is borrowed from GCC and Windows.
  10  * There is NO relation to "transport layer security".
  11  */
  12
  13 /*
  14  * Arbitry limit for thread names for column alignment.
  15  */
  16 #define TR2_MAX_THREAD_NAME (24)
  17
  18 struct tr2tls_thread_ctx {
  19         const char *thread_name;
  20         uint64_t *array_us_start;
  21         size_t alloc;
  22         size_t nr_open_regions; /* plays role of "nr" in ALLOC_GROW */
  23         int thread_id;
  24         struct tr2_timer_block timer_block;
  25         struct tr2_counter_block counter_block;
  26         unsigned int used_any_timer:1;
  27         unsigned int used_any_per_thread_timer:1;
  28         unsigned int used_any_counter:1;
  29         unsigned int used_any_per_thread_counter:1;
  30 };
  31
  32 /*
  33  * Create thread-local storage for the current thread.
  34  *
  35  * The first thread in the process will have:
  36  *     { .thread_id=0, .thread_name="main" }
  37  * Subsequent threads are given a non-zero thread_id and a thread_name
  38  * constructed from the id and a thread base name (which is usually just
  39  * the name of the thread-proc function).  For example:
  40  *     { .thread_id=10, .thread_name="th10:fsm-listen" }
  41  * This helps to identify and distinguish messages from concurrent threads.
  42  * The ctx.thread_name field is truncated if necessary to help with column
  43  * alignment in printf-style messages.
  44  *
  45  * In this and all following functions the term "self" refers to the
  46  * current thread.
  47  */
  48 struct tr2tls_thread_ctx *tr2tls_create_self(const char *thread_base_name,
  49                                              uint64_t us_thread_start);
  50
  51 /*
  52  * Get the thread-local storage pointer of the current thread.
  53  */
  54 struct tr2tls_thread_ctx *tr2tls_get_self(void);
  55
  56 /*
  57  * return true if the current thread is the main thread.
  58  */
  59 int tr2tls_is_main_thread(void);
  60
  61 /*
  62  * Free the current thread's thread-local storage.
  63  */
  64 void tr2tls_unset_self(void);
  65
  66 /*
  67  * Begin a new nested region and remember the start time.
  68  */
  69 void tr2tls_push_self(uint64_t us_now);
  70
  71 /*
  72  * End the innermost nested region.
  73  */
  74 void tr2tls_pop_self(void);
  75
  76 /*
  77  * Pop any extra (above the first) open regions on the current
  78  * thread and discard.  During a thread-exit, we should only
  79  * have region[0] that was pushed in trace2_thread_start() if
  80  * the thread exits normally.
  81  */
  82 void tr2tls_pop_unwind_self(void);
  83
  84 /*
  85  * Compute the elapsed time since the innermost region in the
  86  * current thread started and the given time (usually now).
  87  */
  88 uint64_t tr2tls_region_elasped_self(uint64_t us);
  89
  90 /*
  91  * Compute the elapsed time since the main thread started
  92  * and the given time (usually now).  This is assumed to
  93  * be the absolute run time of the process.
  94  */
  95 uint64_t tr2tls_absolute_elapsed(uint64_t us);
  96
  97 /*
  98  * Initialize thread-local storage for Trace2.
  99  */
 100 void tr2tls_init(void);
 101
 102 /*
 103  * Free all Trace2 thread-local storage resources.
 104  */
 105 void tr2tls_release(void);
 106
 107 /*
 108  * Protected increment of an integer.
 109  */
 110 int tr2tls_locked_increment(int *p);
 111
 112 /*
 113  * Capture the process start time and do nothing else.
 114  */
 115 void tr2tls_start_process_clock(void);
 116
 117 /*
 118  * Explicitly lock/unlock our mutex.
 119  */
 120 void tr2tls_lock(void);
 121 void tr2tls_unlock(void);
 122
 123 #endif /* TR2_TLS_H */