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