tr2tls: clarify TLS terminology
Reduce or eliminate use of the term "TLS" in the Trace2 code. The term "TLS" has two popular meanings: "thread-local storage" and "transport layer security". In the Trace2 source, the term is associated with the former. There was concern on the mailing list about it refering to the latter. Update the source and documentation to eliminate the use of the "TLS" term or replace it with the phrase "thread-local storage" to reduce ambiguity. Signed-off-by: Jeff Hostetler <jeffhost@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jeff Hostetler committed
Oct 24, 2022 at 13:41 UTC
5bbb9251378b0e62bb06e72bda0574e06dee4933
5 files changed
+24
-20
Documentation/technical/api-trace2.txt
+4
-4
@@ -685,8 +685,8 @@ The "exec_id" field is a command-unique id and is only useful if the
685
686
`"thread_start"`::
687
This event is generated when a thread is started. It is
688
- generated from *within* the new thread's thread-proc (for TLS
689
- reasons).
688
+ generated from *within* the new thread's thread-proc (because
689
+ it needs to access data in the thread's thread-local storage).
690
+
691
------------
692
{
@@ -698,7 +698,7 @@ The "exec_id" field is a command-unique id and is only useful if the
698
699
`"thread_exit"`::
700
This event is generated when a thread exits. It is generated
701
- from *within* the thread's thread-proc (for TLS reasons).
701
+ from *within* the thread's thread-proc.
702
+
703
------------
704
{
@@ -1206,7 +1206,7 @@ worked on 508 items at offset 2032. Thread "th04" worked on 508 items
1206
at offset 508.
1207
+
1208
This example also shows that thread names are assigned in a racy manner
1209
-as each thread starts and allocates TLS storage.
1209
+as each thread starts.
1210
1211
Config (def param) Events::
1212
trace2.c
+1
-1
@@ -52,7 +52,7 @@ static struct tr2_tgt *tr2_tgt_builtins[] =
52
* Force (rather than lazily) initialize any of the requested
53
* builtin TRACE2 targets at startup (and before we've seen an
54
* actual TRACE2 event call) so we can see if we need to setup
55
- * the TR2 and TLS machinery.
55
+ * private data structures and thread-local storage.
56
*
57
* Return the number of builtin targets enabled.
58
*/
trace2.h
+5
-5
@@ -73,8 +73,7 @@ void trace2_initialize_clock(void);
73
/*
74
* Initialize TRACE2 tracing facility if any of the builtin TRACE2
75
* targets are enabled in the system config or the environment.
76
- * This includes setting up the Trace2 thread local storage (TLS).
77
- * Emits a 'version' message containing the version of git
76
+ * This emits a 'version' message containing the version of git
77
* and the Trace2 protocol.
78
*
79
* This function should be called from `main()` as early as possible in
@@ -302,7 +301,8 @@ void trace2_exec_result_fl(const char *file, int line, int exec_id, int code);
301
302
/*
303
* Emit a 'thread_start' event. This must be called from inside the
305
- * thread-proc to set up the trace2 TLS data for the thread.
304
+ * thread-proc to allow the thread to create its own thread-local
305
+ * storage.
306
*
307
* Thread names should be descriptive, like "preload_index".
308
* Thread names will be decorated with an instance number automatically.
@@ -315,8 +315,8 @@ void trace2_thread_start_fl(const char *file, int line,
315
316
/*
317
* Emit a 'thread_exit' event. This must be called from inside the
318
- * thread-proc to report thread-specific data and cleanup TLS data
319
- * for the thread.
318
+ * thread-proc so that the thread can access and clean up its
319
+ * thread-local storage.
320
*/
321
void trace2_thread_exit_fl(const char *file, int line);
322
trace2/tr2_tls.c
+3
-3
@@ -69,9 +69,9 @@ struct tr2tls_thread_ctx *tr2tls_get_self(void)
69
ctx = pthread_getspecific(tr2tls_key);
70
71
/*
72
- * If the thread-proc did not call trace2_thread_start(), we won't
73
- * have any TLS data associated with the current thread. Fix it
74
- * here and silently continue.
72
+ * If the current thread's thread-proc did not call
73
+ * trace2_thread_start(), then the thread will not have any
74
+ * thread-local storage. Create it now and silently continue.
75
*/
76
if (!ctx)
77
ctx = tr2tls_create_self("unknown", getnanotime() / 1000);
trace2/tr2_tls.h
+11
-7
@@ -3,6 +3,12 @@
3
4
#include "strbuf.h"
5
6
+/*
7
+ * Notice: the term "TLS" refers to "thread-local storage" in the
8
+ * Trace2 source files. This usage is borrowed from GCC and Windows.
9
+ * There is NO relation to "transport layer security".
10
+ */
11
+
12
/*
13
* Arbitry limit for thread names for column alignment.
14
*/
@@ -17,9 +23,7 @@ struct tr2tls_thread_ctx {
23
};
24
25
/*
20
- * Create TLS data for the current thread. This gives us a place to
21
- * put per-thread data, such as thread start time, function nesting
22
- * and a per-thread label for our messages.
26
+ * Create thread-local storage for the current thread.
27
*
28
* We assume the first thread is "main". Other threads are given
29
* non-zero thread-ids to help distinguish messages from concurrent
@@ -35,7 +39,7 @@ struct tr2tls_thread_ctx *tr2tls_create_self(const char *thread_name,
39
uint64_t us_thread_start);
40
41
/*
38
- * Get our TLS data.
42
+ * Get the thread-local storage pointer of the current thread.
43
*/
44
struct tr2tls_thread_ctx *tr2tls_get_self(void);
45
@@ -45,7 +49,7 @@ struct tr2tls_thread_ctx *tr2tls_get_self(void);
49
int tr2tls_is_main_thread(void);
50
51
/*
48
- * Free our TLS data.
52
+ * Free the current thread's thread-local storage.
53
*/
54
void tr2tls_unset_self(void);
55
@@ -81,12 +85,12 @@ uint64_t tr2tls_region_elasped_self(uint64_t us);
85
uint64_t tr2tls_absolute_elapsed(uint64_t us);
86
87
/*
84
- * Initialize the tr2 TLS system.
88
+ * Initialize thread-local storage for Trace2.
89
*/
90
void tr2tls_init(void);
91
92
/*
89
- * Free all tr2 TLS resources.
93
+ * Free all Trace2 thread-local storage resources.
94
*/
95
void tr2tls_release(void);
96