trace: move doc to trace.h
Move the documentation from Documentation/technical/api-trace.txt to trace.h as it's easier for the developers to find the usage information beside the code instead of looking for it in another doc file. Documentation/technical/api-trace.txt is removed because the information it has is now redundant and it'll be hard to keep it up to date and synchronized with the documentation in the header file. Signed-off-by: Heba Waly <heba.waly@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Heba Waly committed
Nov 17, 2019 at 21:04 UTC
f1ecbe0f539ad8cb40cadb69e369cf42aa975d33
2 files changed
+131
-142
Documentation/technical/api-trace.txt
deleted
-140
@@ -1,140 +0,0 @@
1
-trace API
2
-=========
3
-
4
-The trace API can be used to print debug messages to stderr or a file. Trace
5
-code is inactive unless explicitly enabled by setting `GIT_TRACE*` environment
6
-variables.
7
-
8
-The trace implementation automatically adds `timestamp file:line ... \n` to
9
-all trace messages. E.g.:
10
-
11
-------------
12
-23:59:59.123456 git.c:312 trace: built-in: git 'foo'
13
-00:00:00.000001 builtin/foo.c:99 foo: some message
14
-------------
15
-
16
-Data Structures
17
----------------
18
-
19
-`struct trace_key`::
20
-
21
- Defines a trace key (or category). The default (for API functions that
22
- don't take a key) is `GIT_TRACE`.
23
-+
24
-E.g. to define a trace key controlled by environment variable `GIT_TRACE_FOO`:
25
-+
26
-------------
27
-static struct trace_key trace_foo = TRACE_KEY_INIT(FOO);
28
-
29
-static void trace_print_foo(const char *message)
30
-{
31
- trace_printf_key(&trace_foo, "%s", message);
32
-}
33
-------------
34
-+
35
-Note: don't use `const` as the trace implementation stores internal state in
36
-the `trace_key` structure.
37
-
38
-Functions
39
----------
40
-
41
-`int trace_want(struct trace_key *key)`::
42
-
43
- Checks whether the trace key is enabled. Used to prevent expensive
44
- string formatting before calling one of the printing APIs.
45
-
46
-`void trace_disable(struct trace_key *key)`::
47
-
48
- Disables tracing for the specified key, even if the environment
49
- variable was set.
50
-
51
-`void trace_printf(const char *format, ...)`::
52
-`void trace_printf_key(struct trace_key *key, const char *format, ...)`::
53
-
54
- Prints a formatted message, similar to printf.
55
-
56
-`void trace_argv_printf(const char **argv, const char *format, ...)``::
57
-
58
- Prints a formatted message, followed by a quoted list of arguments.
59
-
60
-`void trace_strbuf(struct trace_key *key, const struct strbuf *data)`::
61
-
62
- Prints the strbuf, without additional formatting (i.e. doesn't
63
- choke on `%` or even `\0`).
64
-
65
-`uint64_t getnanotime(void)`::
66
-
67
- Returns nanoseconds since the epoch (01/01/1970), typically used
68
- for performance measurements.
69
-+
70
-Currently there are high precision timer implementations for Linux (using
71
-`clock_gettime(CLOCK_MONOTONIC)`) and Windows (`QueryPerformanceCounter`).
72
-Other platforms use `gettimeofday` as time source.
73
-
74
-`void trace_performance(uint64_t nanos, const char *format, ...)`::
75
-`void trace_performance_since(uint64_t start, const char *format, ...)`::
76
-
77
- Prints the elapsed time (in nanoseconds), or elapsed time since
78
- `start`, followed by a formatted message. Enabled via environment
79
- variable `GIT_TRACE_PERFORMANCE`. Used for manual profiling, e.g.:
80
-+
81
-------------
82
-uint64_t start = getnanotime();
83
-/* code section to measure */
84
-trace_performance_since(start, "foobar");
85
-------------
86
-+
87
-------------
88
-uint64_t t = 0;
89
-for (;;) {
90
- /* ignore */
91
- t -= getnanotime();
92
- /* code section to measure */
93
- t += getnanotime();
94
- /* ignore */
95
-}
96
-trace_performance(t, "frotz");
97
-------------
98
-
99
-Bugs & Caveats
100
---------------
101
-
102
-GIT_TRACE_* environment variables can be used to tell Git to show
103
-trace output to its standard error stream. Git can often spawn a pager
104
-internally to run its subcommand and send its standard output and
105
-standard error to it.
106
-
107
-Because GIT_TRACE_PERFORMANCE trace is generated only at the very end
108
-of the program with atexit(), which happens after the pager exits, it
109
-would not work well if you send its log to the standard error output
110
-and let Git spawn the pager at the same time.
111
-
112
-As a work around, you can for example use '--no-pager', or set
113
-GIT_TRACE_PERFORMANCE to another file descriptor which is redirected
114
-to stderr, or set GIT_TRACE_PERFORMANCE to a file specified by its
115
-absolute path.
116
-
117
-For example instead of the following command which by default may not
118
-print any performance information:
119
-
120
-------------
121
-GIT_TRACE_PERFORMANCE=2 git log -1
122
-------------
123
-
124
-you may want to use:
125
-
126
-------------
127
-GIT_TRACE_PERFORMANCE=2 git --no-pager log -1
128
-------------
129
-
130
-or:
131
-
132
-------------
133
-GIT_TRACE_PERFORMANCE=3 3>&2 git log -1
134
-------------
135
-
136
-or:
137
-
138
-------------
139
-GIT_TRACE_PERFORMANCE=/path/to/log/file git log -1
140
-------------
trace.h
+131
-2
@@ -4,6 +4,82 @@
4
#include "git-compat-util.h"
5
#include "strbuf.h"
6
7
+/**
8
+ * The trace API can be used to print debug messages to stderr or a file. Trace
9
+ * code is inactive unless explicitly enabled by setting `GIT_TRACE*` environment
10
+ * variables.
11
+ *
12
+ * The trace implementation automatically adds `timestamp file:line ... \n` to
13
+ * all trace messages. E.g.:
14
+ *
15
+ * ------------
16
+ * 23:59:59.123456 git.c:312 trace: built-in: git 'foo'
17
+ * 00:00:00.000001 builtin/foo.c:99 foo: some message
18
+ * ------------
19
+ *
20
+ * Bugs & Caveats
21
+ * --------------
22
+ *
23
+ * GIT_TRACE_* environment variables can be used to tell Git to show
24
+ * trace output to its standard error stream. Git can often spawn a pager
25
+ * internally to run its subcommand and send its standard output and
26
+ * standard error to it.
27
+ *
28
+ * Because GIT_TRACE_PERFORMANCE trace is generated only at the very end
29
+ * of the program with atexit(), which happens after the pager exits, it
30
+ * would not work well if you send its log to the standard error output
31
+ * and let Git spawn the pager at the same time.
32
+ *
33
+ * As a work around, you can for example use '--no-pager', or set
34
+ * GIT_TRACE_PERFORMANCE to another file descriptor which is redirected
35
+ * to stderr, or set GIT_TRACE_PERFORMANCE to a file specified by its
36
+ * absolute path.
37
+ *
38
+ * For example instead of the following command which by default may not
39
+ * print any performance information:
40
+ *
41
+ * ------------
42
+ * GIT_TRACE_PERFORMANCE=2 git log -1
43
+ * ------------
44
+ *
45
+ * you may want to use:
46
+ *
47
+ * ------------
48
+ * GIT_TRACE_PERFORMANCE=2 git --no-pager log -1
49
+ * ------------
50
+ *
51
+ * or:
52
+ *
53
+ * ------------
54
+ * GIT_TRACE_PERFORMANCE=3 3>&2 git log -1
55
+ * ------------
56
+ *
57
+ * or:
58
+ *
59
+ * ------------
60
+ * GIT_TRACE_PERFORMANCE=/path/to/log/file git log -1
61
+ * ------------
62
+ *
63
+ */
64
+
65
+/**
66
+ * Defines a trace key (or category). The default (for API functions that
67
+ * don't take a key) is `GIT_TRACE`.
68
+ *
69
+ * E.g. to define a trace key controlled by environment variable `GIT_TRACE_FOO`:
70
+ *
71
+ * ------------
72
+ * static struct trace_key trace_foo = TRACE_KEY_INIT(FOO);
73
+ *
74
+ * static void trace_print_foo(const char *message)
75
+ * {
76
+ * trace_printf_key(&trace_foo, "%s", message);
77
+ * }
78
+ * ------------
79
+ *
80
+ * Note: don't use `const` as the trace implementation stores internal state in
81
+ * the `trace_key` structure.
82
+ */
83
struct trace_key {
84
const char * const key;
85
int fd;
@@ -18,31 +94,84 @@ extern struct trace_key trace_perf_key;
94
extern struct trace_key trace_setup_key;
95
96
void trace_repo_setup(const char *prefix);
97
+
98
+/**
99
+ * Checks whether the trace key is enabled. Used to prevent expensive
100
+ * string formatting before calling one of the printing APIs.
101
+ */
102
int trace_want(struct trace_key *key);
103
+
104
+/**
105
+ * Disables tracing for the specified key, even if the environment variable
106
+ * was set.
107
+ */
108
void trace_disable(struct trace_key *key);
109
+
110
+/**
111
+ * Returns nanoseconds since the epoch (01/01/1970), typically used
112
+ * for performance measurements.
113
+ * Currently there are high precision timer implementations for Linux (using
114
+ * `clock_gettime(CLOCK_MONOTONIC)`) and Windows (`QueryPerformanceCounter`).
115
+ * Other platforms use `gettimeofday` as time source.
116
+ */
117
uint64_t getnanotime(void);
118
+
119
void trace_command_performance(const char **argv);
120
void trace_verbatim(struct trace_key *key, const void *buf, unsigned len);
121
uint64_t trace_performance_enter(void);
122
123
#ifndef HAVE_VARIADIC_MACROS
124
125
+/**
126
+ * Prints a formatted message, similar to printf.
127
+ */
128
__attribute__((format (printf, 1, 2)))
129
void trace_printf(const char *format, ...);
130
131
__attribute__((format (printf, 2, 3)))
132
void trace_printf_key(struct trace_key *key, const char *format, ...);
133
134
+/**
135
+ * Prints a formatted message, followed by a quoted list of arguments.
136
+ */
137
__attribute__((format (printf, 2, 3)))
138
void trace_argv_printf(const char **argv, const char *format, ...);
139
140
+/**
141
+ * Prints the strbuf, without additional formatting (i.e. doesn't
142
+ * choke on `%` or even `\0`).
143
+ */
144
void trace_strbuf(struct trace_key *key, const struct strbuf *data);
145
41
-/* Prints elapsed time (in nanoseconds) if GIT_TRACE_PERFORMANCE is enabled. */
146
+/**
147
+ * Prints elapsed time (in nanoseconds) if GIT_TRACE_PERFORMANCE is enabled.
148
+ *
149
+ * Example:
150
+ * ------------
151
+ * uint64_t t = 0;
152
+ * for (;;) {
153
+ * // ignore
154
+ * t -= getnanotime();
155
+ * // code section to measure
156
+ * t += getnanotime();
157
+ * // ignore
158
+ * }
159
+ * trace_performance(t, "frotz");
160
+ * ------------
161
+ */
162
__attribute__((format (printf, 2, 3)))
163
void trace_performance(uint64_t nanos, const char *format, ...);
164
45
-/* Prints elapsed time since 'start' if GIT_TRACE_PERFORMANCE is enabled. */
165
+/**
166
+ * Prints elapsed time since 'start' if GIT_TRACE_PERFORMANCE is enabled.
167
+ *
168
+ * Example:
169
+ * ------------
170
+ * uint64_t start = getnanotime();
171
+ * // code section to measure
172
+ * trace_performance_since(start, "foobar");
173
+ * ------------
174
+ */
175
__attribute__((format (printf, 2, 3)))
176
void trace_performance_since(uint64_t start, const char *format, ...);
177