Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
Loading...
Searching...
No Matches
qtrace_p.h
Go to the documentation of this file.
1
// Copyright (C) 2017 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Rafael Roquetto <rafael.roquetto@kdab.com>
2
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4
#ifndef QTRACE_P_H
5
#define QTRACE_P_H
6
7
//
8
// W A R N I N G
9
// -------------
10
//
11
// This file is not part of the Qt API. It exists purely as an
12
// implementation detail. This header file may change from version to
13
// version without notice, or even be removed.
14
//
15
// We mean it.
16
//
17
18
/*
19
* The Qt tracepoints API consists of only five macros:
20
*
21
* - Q_TRACE(tracepoint, args...)
22
* Fires 'tracepoint' if it is enabled.
23
*
24
* - Q_TRACE_EXIT(tracepoint, args...)
25
* Fires 'tracepoint' if it is enabled when the current scope exists.
26
*
27
* - Q_TRACE_SCOPE(tracepoint, args...)
28
* Wrapper around Q_TRACE/_EXIT to trace entry and exit. First it traces
29
* `${tracepoint}_entry` and then `${tracepoint}_exit` on scope exit.
30
*
31
* - Q_UNCONDITIONAL_TRACE(tracepoint, args...)
32
* Fires 'tracepoint' unconditionally: no check is performed to query
33
* whether 'tracepoint' is enabled.
34
*
35
* - Q_TRACE_ENABLED(tracepoint)
36
* Returns 'true' if 'tracepoint' is enabled; false otherwise.
37
*
38
* When using LTTNG, Q_TRACE, Q_UNCONDITIONAL_TRACE and Q_TRACE_ENABLED map
39
* ultimately to tracepoint(), do_tracepoint() and tracepoint_enabled(),
40
* respectively, described on the lttng-ust manpage (man 3 lttng-ust).
41
*
42
* On ETW, Q_TRACE() and Q_UNCONDITIONAL_TRACE() are equivalent, ultimately
43
* amounting to a call to TraceLoggingWrite(), whereas Q_TRACE_ENABLED()
44
* wraps around TraceLoggingProviderEnabled().
45
*
46
* A tracepoint provider is defined in a separate file, that follows the
47
* following format:
48
*
49
* tracepoint_name(arg_type arg_name, ...)
50
*
51
* For instance:
52
*
53
* qcoreapplication_ctor(int argc, const char * const argv)
54
* qcoreapplication_foo(int argc, const char[10] argv)
55
* qcoreapplication_baz(const char[len] some_string, unsigned int len)
56
* qcoreapplication_qstring(const QString &foo)
57
* qcoreapplication_qrect(const QRect &rect)
58
*
59
* The provider file is then parsed by src/tools/tracegen, which can be
60
* switched to output either ETW, CTF or LTTNG tracepoint definitions. The provider
61
* name is deduced to be basename(provider_file).
62
*
63
* To use the above (inside qtcore), you need to include
64
* <providername_tracepoints_p.h>. After that, the following call becomes
65
* possible:
66
*
67
* Q_TRACE(qcoreapplication_qrect, myRect);
68
*
69
* Currently, all C++ primitive non-pointer types are supported for
70
* arguments. Additionally, char * is supported, and is assumed to
71
* be a NULL-terminated string. Finally, the following subset of Qt types also
72
* currently supported:
73
*
74
* - QString
75
* - QByteArray
76
* - QUrl
77
* - QRect
78
* - QRectF
79
* - QSize
80
* - QSizeF
81
*
82
* Dynamic arrays are supported using the syntax illustrated by
83
* qcoreapplication_baz above.
84
*
85
* One can also add prefix for the generated providername_tracepoints_p.h file
86
* by specifying it inside brackets '{ }' in the tracepoints file. One can
87
* for example add forward declaration for a type:
88
*
89
* {
90
* QT_BEGIN_NAMESPACE
91
* class QEvent;
92
* QT_END_NAMESPACE
93
* }
94
*
95
* Metadata
96
*
97
* Metadata is used to add textual information for different types such
98
* as enums and flags. How this data is handled depends on the used backend.
99
* For ETW, the values are converted to text, for CTF and LTTNG they are used to add
100
* CTF enumerations, which are converted to text after tracing.
101
*
102
* Enumererations are specified using ENUM:
103
*
104
* ENUM {
105
* Enum0 = 0,
106
* Enum1 = 1,
107
* Enum2,
108
* RANGE(RangeEnum, 3 ... 10),
109
* } Name;
110
*
111
* Name must match to one of the enumerations used in the tracepoints. Range of values
112
* can be provided using RANGE(name, first ... last). All values must be unique.
113
*
114
* Flags are specified using FLAGS:
115
*
116
* FLAGS {
117
* Default = 0,
118
* Flag0 = 1,
119
* Flag1 = 2,
120
* Flag2 = 4,
121
* } Name;
122
*
123
* Name must match to one of the flags used in the tracepoints. Each value must be
124
* power of two and unique.
125
*/
126
127
#include <QtCore/private/qglobal_p.h>
128
#include <QtCore/qscopeguard.h>
129
130
QT_BEGIN_NAMESPACE
131
132
#if defined(Q_TRACEPOINT) && !defined(QT_BOOTSTRAPPED)
133
# define Q_HAS_TRACEPOINTS 1
134
# define Q_TRACE(x, ...) QtPrivate::trace_ ## x(__VA_ARGS__)
135
# define Q_TRACE_EXIT(x, ...) \
136
const auto qTraceExit_ ## x ## __COUNTER__ = qScopeGuard([&]() { Q_TRACE(x, __VA_ARGS__); });
137
# define Q_TRACE_SCOPE(x, ...) \
138
Q_TRACE(x ## _entry, __VA_ARGS__); \
139
Q_TRACE_EXIT(x ## _exit);
140
# define Q_UNCONDITIONAL_TRACE(x, ...) QtPrivate::do_trace_ ## x(__VA_ARGS__)
141
# define Q_TRACE_ENABLED(x) QtPrivate::trace_ ## x ## _enabled()
142
#else
143
# define Q_HAS_TRACEPOINTS 0
144
# define Q_TRACE(x, ...)
145
# define Q_TRACE_EXIT(x, ...)
146
# define Q_TRACE_SCOPE(x, ...)
147
# define Q_UNCONDITIONAL_TRACE(x, ...)
148
# define Q_TRACE_ENABLED(x) false
149
#endif
// defined(Q_TRACEPOINT) && !defined(QT_BOOTSTRAPPED)
150
151
152
/*
153
* The Qt tracepoints can also be defined directly in the source files using
154
* the following macros. If using these macros, the tracepoints file is automatically
155
* generated using the tracepointgen tool. The tool scans the input files for
156
* these macros. These macros are ignored during compile time. Both automatic
157
* generation and manually specifying tracepoints in a file can't be done at the same
158
* time for the same provider.
159
*
160
* - Q_TRACE_INSTRUMENT(provider)
161
* Generate entry/exit tracepoints for a function. For example, member function
162
*
163
* void SomeClass::method(int param1, float param2)
164
* {
165
* ...
166
* }
167
*
168
* converted to use tracepoints:
169
*
170
* void Q_TRACE_INSTRUMENT(provider) SomeClass::method(int param1, float param2)
171
* {
172
* Q_TRACE_SCOPE(SomeClass_method, param1, param2);
173
* ...
174
* }
175
*
176
* generates following tracepoints in provider.tracepoints file:
177
*
178
* SomeClass_method_entry(int param1, float param2)
179
* SomeClass_method_exit()
180
*
181
* - Q_TRACE_PARAM_REPLACE(in, out)
182
* Can be used with Q_TRACE_INSTRUMENT to replace parameter type in with type out.
183
* If a parameter type is not supported by the tracegen tool, one can use this to
184
* change it to another supported type.
185
*
186
* void Q_TRACE_INSTRUMENT(provider) SomeClass::method(int param1, UserType param2)
187
* {
188
* Q_TRACE_PARAM_REPLACE(UserType, QString);
189
* Q_TRACE_SCOPE(SomeClass_method, param1, param2.toQString());
190
* }
191
*
192
* - Q_TRACE_POINT(provider, tracepoint, ...)
193
* Manually specify tracepoint for the provider. 'tracepoint' is the full name
194
* of the tracepoint and ... can be zero or more parameters.
195
*
196
* Q_TRACE_POINT(provider, SomeClass_function_entry, int param1, int param2);
197
*
198
* generates following tracepoint:
199
*
200
* SomeClass_function_entry(int param1, int param2)
201
*
202
* - Q_TRACE_PREFIX(provider, prefix)
203
* Provide prefix for the tracepoint. Multiple prefixes can be specified for the same
204
* provider in different files, they are all concatenated into one in the
205
* provider.tracepoints file.
206
*
207
* Q_TRACE_PREFIX(provider,
208
* "QT_BEGIN_NAMESPACE" \
209
* "class QEvent;" \
210
* "QT_END_NAMESPACE")
211
*
212
* - Q_TRACE_METADATA(provider, metadata)
213
* Provides metadata for the tracepoint provider.
214
*
215
* Q_TRACE_METADATA(qtgui,
216
* "ENUM {" \
217
* "Format_Invalid," \
218
* "Format_Mono," \
219
* "Format_MonoLSB," \
220
* "Format_Indexed8," \
221
* ...
222
* "} QImage::Format;" \
223
* );
224
*
225
* If the content of enum is empty or contains keyword AUTO, then the tracepointgen tool
226
* tries to find the enumeration from header files.
227
*
228
* Q_TRACE_METADATA(qtcore, "ENUM { AUTO, RANGE User ... MaxUser } QEvent::Type;");
229
*/
230
#define Q_TRACE_INSTRUMENT(provider)
231
#define Q_TRACE_PARAM_REPLACE(in, out)
232
#define Q_TRACE_POINT(provider, tracepoint, ...)
233
#define Q_TRACE_PREFIX(provider, prefix)
234
#define Q_TRACE_METADATA(provider, metadata)
235
236
QT_END_NAMESPACE
237
238
#endif
// QTRACE_P_H
QT_BEGIN_NAMESPACE
Combined button and popup list for selecting options.
Definition
qstandardpaths_haiku.cpp:21
QT_END_NAMESPACE
Definition
qsharedpointer.cpp:1590
qtbase
src
corelib
global
qtrace_p.h
Generated by
1.10.0