MySQL 8.3.0
Source Code Documentation
opt_trace_context.h
Go to the documentation of this file.
1/* Copyright (c) 2011, 2023, Oracle and/or its affiliates.
2
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License, version 2.0,
5 as published by the Free Software Foundation.
6
7 This program is also distributed with certain software (including
8 but not limited to OpenSSL) that is licensed under separate terms,
9 as designated in a particular file or component or in included license
10 documentation. The authors of MySQL hereby grant you an additional
11 permission to link the program and your derivative works with the
12 separately licensed software that they have included with MySQL.
13
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License, version 2.0, for more details.
18
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22
23#ifndef OPT_TRACE_CONTEXT_INCLUDED
24#define OPT_TRACE_CONTEXT_INCLUDED
25
26#include <assert.h>
27
28#include "my_inttypes.h"
30#include "prealloced_array.h"
31
32struct CHARSET_INFO;
33
34/**
35 @file
36 This contains the declaration of class Opt_trace_context, which is needed
37 to declare THD.
38 It is recommend to read opt_trace.h first.
39*/
40
41class Opt_trace_stmt; // implementation detail local to opt_trace.cc
42
44
45/**
46 @class Opt_trace_context
47
48 A per-session context which is always available at any point of execution,
49 because in practice it's accessible from THD which contains:
50 @verbatim Opt_trace_context opt_trace; @endverbatim
51 It maintains properties of the session's regarding tracing: enabled/disabled
52 state, style (all trace on one line, or not, etc), a list of all remembered
53 traces of previous and current SQL statement (as restricted by
54 OFFSET/LIMIT), and a pointer to the current (being-generated) trace (which
55 itself has a pointer to its current open object/array).
56
57 Here is why the context needs to provide the current open object/array:
58
59 @li When adding a value (scalar or array or object) to an array, or adding a
60 key/value pair to an object, we need this outer object or array (from now
61 on, we will use the term "structure" for "object or array", as both are
62 structured types).
63
64 @li The most natural way would be that the outer object would be passed in
65 argument to the adder (the function which wants to add the value or
66 key/value).
67
68 @li But tracing is sometimes produced from deep down the stack trace, with
69 many intermediate frames doing no tracing (writing nothing to the trace), so
70 it would require passing the outer structure through many levels, thus
71 modifying many function prototypes.
72 Example (in gdb "backtrace" notation: inner frames first):
73@verbatim
74 #0 Item_in_subselect::single_value_transformer
75 - opens an object for key "transformation"
76 #1 Item_in_subselect::select_in_like_transformer - does no tracing
77 #2 Item_allany_subselect::select_transformer - does no tracing
78 #3 Query_block::prepare - opens an object for key "join_preparation"
79@endverbatim
80 So the object opened in #3 would have to be passed in argument to #2 and #1
81 in order to finally reach #0 where object "transformation" would be added to
82 it.
83
84 @li So, as we cannot practically pass the object down, we rather maintain a
85 "current object or array" accessible from the Opt_trace_context context;
86 it's a pointer to an instance of Opt_trace_struct, and the function deep
87 down (frame #0) grabs it from the context, where it was depositted by the
88 function high up (frame #3 in the last example).
89*/
90
92 public:
95
96 /**
97 Starts a new trace.
98 @param support_I_S Whether this statement should have its trace in
99 information_schema
100 @param support_dbug_or_missing_priv 'true' if this statement
101 should have its trace in the dbug log (--debug),
102 or if missing_privilege() may be called on this
103 trace
104 @param end_marker For a key/(object|array) pair, should the key be
105 repeated in a comment when the object|array
106 closes? like
107 @verbatim
108 "key_foo": {
109 multi-line blah
110 } / * key_foo * /
111 @endverbatim
112 This is for human-readability only, not valid in
113 JSON. Note that YAML supports #-prefixed
114 comments (we would just need to put the next
115 item's "," before the current item's "#").
116 @param one_line Should the trace be on a single line without
117 indentation? (More compact for network transfer
118 to programs, less human-readable.)
119 @param offset Offset for restricting trace production.
120 @param limit Limit for restricting trace production.
121 @param max_mem_size Maximum allowed for cumulated size of all
122 remembered traces.
123 @param features Only these optimizer features should be traced.
124
125 @retval false ok
126 @retval true error (OOM): instance is unusable, so only
127 destructor is permitted on it; any other
128 member function has undefined effects.
129 */
130 bool start(bool support_I_S, bool support_dbug_or_missing_priv,
131 bool end_marker, bool one_line, long offset, long limit,
132 ulong max_mem_size, ulonglong features);
133
134 /**
135 Ends the current (=open, unfinished, being-generated) trace.
136
137 If @c missing_privilege() has been called between start() and end(),
138 end() restores I_S support to what it was before the call to
139 @c missing_privilege(). This is the key to ensure that missing_privilege()
140 does not disable I_S support for the rest of the connection's life!
141 */
142 void end();
143
144 /// Returns whether there is a current trace
145 bool is_started() const {
146 return unlikely(pimpl != nullptr) && pimpl->current_stmt_in_gen != nullptr;
147 }
148
149 /**
150 @returns whether the current trace writes to I_S.
151 This function should rarely be used. Don't you use this for some clever
152 optimizations bypassing opt trace!
153 */
154 bool support_I_S() const;
155
156 /**
157 Set the "original" query (not transformed, as sent by client) for the
158 current trace.
159 @param query query
160 @param length query's length
161 @param charset charset which was used to encode this query
162 */
163 void set_query(const char *query, size_t length, const CHARSET_INFO *charset);
164
165 /**
166 Brainwash: deletes all remembered traces and resets counters regarding
167 OFFSET/LIMIT (so that the next statement is considered as "at offset
168 0"). Does not reset the @@@@optimizer_trace_offset/limit variables.
169 */
170 void reset();
171
172 /// @sa parameters of Opt_trace_context::start()
173 bool get_end_marker() const { return pimpl->end_marker; }
174 /// @sa parameters of Opt_trace_context::start()
175 bool get_one_line() const { return pimpl->one_line; }
176
177 /**
178 Names of flags for @@@@optimizer_trace variable of @c sys_vars.cc :
179 @li "enabled" = tracing enabled
180 @li "one_line"= see parameter of @ref Opt_trace_context::start
181 @li "default".
182 */
183 static const char *flag_names[];
184
185 /** Flags' numeric values for @@@@optimizer_trace variable */
186 enum { FLAG_DEFAULT = 0, FLAG_ENABLED = 1 << 0, FLAG_ONE_LINE = 1 << 1 };
187
188 /**
189 Features' names for @@@@optimizer_trace_features variable of
190 @c sys_vars.cc:
191 @li "greedy_search" = the greedy search for a plan
192 @li "range_optimizer" = the cost analysis of accessing data through
193 ranges in indexes
194 @li "dynamic_range" = the range optimization performed for each record
195 when access method is dynamic range
196 @li "repeated_subselect" = the repeated execution of subselects
197 @li "default".
198 */
199 static const char *feature_names[];
200
201 /** Features' numeric values for @@@@optimizer_trace_features variable */
207 /*
208 If you add here, update feature_value of empty implementation
209 and default_features!
210 */
211 /**
212 Anything unclassified, including the top object (thus, by "inheritance
213 from parent", disabling MISC makes an empty trace).
214 This feature cannot be disabled by the user; for this it is important
215 that it always has biggest flag; flag's value itself does not matter.
216 */
217 MISC = 1 << 7
218 };
219
220 /**
221 User lacks privileges to see the current trace. Make the trace appear
222 empty in Opt_trace_info, and disable I_S for all its upcoming children.
223
224 Once a call to this function has been made, subsequent calls to it before
225 @c end() have no effects.
226 */
227 void missing_privilege();
228
229 /// Optimizer features which are traced by default.
231
232 /**
233 @returns whether an optimizer feature should be traced.
234 @param f feature
235 */
237 return unlikely(pimpl != nullptr) && (pimpl->features & f);
238 }
239
240 /**
241 Opt_trace_struct is passed Opt_trace_context*, and needs to know
242 to which statement's trace to attach, so Opt_trace_context must provide
243 this information.
244 */
247 }
248
249 /**
250 @returns the next statement to show in I_S.
251 @param[in,out] got_so_far How many statements the caller got so far
252 (by previous calls to this function); function updates this count.
253 @note traces are returned from oldest to newest.
254 */
255 const Opt_trace_stmt *get_next_stmt_for_I_S(long *got_so_far) const;
256
257 /// Temporarily disables I_S for this trace and its children.
259 ++I_S_disabled;
261 }
262
263 /**
264 Restores I_S support to what it was before the previous call to
265 disable_I_S_for_this_and_children().
266 */
267 void restore_I_S() {
268 --I_S_disabled;
269 assert(I_S_disabled >= 0);
270 if (unlikely(pimpl != nullptr)) pimpl->restore_I_S();
271 }
272
273 private:
274 /**
275 To have the smallest impact on THD's size, most of the implementation is
276 moved to a separate class Opt_trace_context_impl which is instantiated on
277 the heap when really needed. So if a connection never sets
278 @@@@optimizer_trace to "enabled=on" and does not use --debug, this heap
279 allocation never happens.
280 This class is declared here so that frequently called functions like
281 Opt_trace_context::is_started() can be inlined.
282 */
284 public:
291 offset(0),
292 limit(0),
293 since_offset_0(0) {}
294
296 void restore_I_S();
297
298 /**
299 Trace which is currently being generated, where structures are being
300 added. "in_gen" stands for "in generation", being-generated.
301
302 In simple cases it is equal to the last element of array
303 all_stmts_for_I_S. But it can be prior to it, for example when calling
304 a stored routine:
305@verbatim
306 CALL statement starts executing
307 create trace of CALL (call it "trace #1")
308 add structure to trace #1
309 add structure to trace #1
310 First sub-statement executing
311 create trace of sub-statement (call it "trace #2")
312 add structure to trace #2
313 add structure to trace #2
314 First sub-statement ends
315 add structure to trace #1
316@endverbatim
317 In the beginning, the CALL statement's trace is the newest and current;
318 when the first sub-statement is executing, that sub-statement's trace
319 is the newest and current; when the first sub-statement ends, it is
320 still the newest but it's not the current anymore: the current is then
321 again the CALL's one, where structures will be added, until a second
322 sub-statement is executed.
323 Another case is when the current statement sends only to DBUG:
324 all_stmts_for_I_S lists only traces shown in OPTIMIZER_TRACE.
325 */
327
328 /**
329 To keep track of what is the current statement, as execution goes into
330 a sub-statement, and back to the upper statement, we have a stack of
331 successive values of current_stmt_in_gen:
332 when in a statement we enter a substatement (a new trace), we push the
333 statement's trace on the stack and change current_stmt_in_gen to the
334 substatement's trace; when leaving the substatement we pop from the
335 stack and set current_stmt_in_gen to the popped value.
336 */
338
339 /**
340 List of remembered traces for putting into the OPTIMIZER_TRACE
341 table. Element 0 is the one created first, will be first row of
342 OPTIMIZER_TRACE table. The array structure fulfills those needs:
343 - to output traces "oldest first" in OPTIMIZER_TRACE
344 - to preserve traces "newest first" when @@@@optimizer_trace_offset<0
345 - to delete a trace in the middle of the list when it is permanently
346 out of the offset/limit showable window.
347 */
349 /**
350 List of traces which are unneeded because of OFFSET/LIMIT, and
351 scheduled for deletion from memory.
352 */
354
355 bool end_marker; ///< copy of parameter of Opt_trace_context::start
358 long offset;
359 long limit;
361
362 /**
363 Number of statements traced so far since "offset 0", for comparison
364 with OFFSET and LIMIT, when OFFSET >= 0.
365 */
367 };
368
369 Opt_trace_context_impl *pimpl; /// Dynamically allocated implementation.
370
371 /**
372 <>0 <=> any to-be-created statement's trace should not be in
373 information_schema. This applies to next statements, their substatements,
374 etc.
375 */
377
378 /**
379 Find and delete unneeded traces.
380 For example if OFFSET=-1,LIMIT=1, only the last trace is needed. When a
381 new trace is started, the previous traces becomes unneeded and this
382 function deletes them which frees memory.
383 @param purge_all if true, ignore OFFSET and thus delete everything
384 */
385 void purge_stmts(bool purge_all);
386
387 /**
388 Compute maximum allowed memory size for current trace. The current trace
389 is the only one active. Other traces break down in two groups:
390 - the finished ones (from previously executed statements),
391 - the "started but not finished ones": they are not current, are not
392 being updated at this moment: this must be the trace of a top
393 statement calling a substatement which is the current trace now: trace's
394 top statement is not being updated at this moment.
395 So the current trace can grow in the room left by all traces above.
396 */
398
399 /// Not defined copy constructor, to disallow copy.
401 /// Not defined assignment operator, to disallow assignment.
403};
404
405#endif /* OPT_TRACE_CONTEXT_INCLUDED */
Kerberos Client Authentication nullptr
Definition: auth_kerberos_client_plugin.cc:250
To have the smallest impact on THD's size, most of the implementation is moved to a separate class Op...
Definition: opt_trace_context.h:283
Opt_trace_stmt_array stack_of_current_stmts
To keep track of what is the current statement, as execution goes into a sub-statement,...
Definition: opt_trace_context.h:337
Opt_trace_stmt_array all_stmts_to_del
List of traces which are unneeded because of OFFSET/LIMIT, and scheduled for deletion from memory.
Definition: opt_trace_context.h:353
size_t max_mem_size
Definition: opt_trace_context.h:360
long since_offset_0
Number of statements traced so far since "offset 0", for comparison with OFFSET and LIMIT,...
Definition: opt_trace_context.h:366
void restore_I_S()
Definition: opt_trace.cc:1114
void disable_I_S_for_this_and_children()
Definition: opt_trace.cc:1110
long offset
Definition: opt_trace_context.h:358
Opt_trace_context_impl()
Definition: opt_trace_context.h:285
bool end_marker
copy of parameter of Opt_trace_context::start
Definition: opt_trace_context.h:355
Opt_trace_stmt * current_stmt_in_gen
Definition: opt_trace_context.h:326
feature_value features
Definition: opt_trace_context.h:357
long limit
Definition: opt_trace_context.h:359
Opt_trace_stmt_array all_stmts_for_I_S
List of remembered traces for putting into the OPTIMIZER_TRACE table.
Definition: opt_trace_context.h:348
bool one_line
Definition: opt_trace_context.h:356
A per-session context which is always available at any point of execution, because in practice it's a...
Definition: opt_trace_context.h:91
bool get_end_marker() const
Definition: opt_trace_context.h:173
bool get_one_line() const
Definition: opt_trace_context.h:175
@ FLAG_ONE_LINE
Definition: opt_trace_context.h:186
@ FLAG_ENABLED
Definition: opt_trace_context.h:186
@ FLAG_DEFAULT
Definition: opt_trace_context.h:186
bool start(bool support_I_S, bool support_dbug_or_missing_priv, bool end_marker, bool one_line, long offset, long limit, ulong max_mem_size, ulonglong features)
Starts a new trace.
Definition: opt_trace.cc:820
void purge_stmts(bool purge_all)
Find and delete unneeded traces.
Definition: opt_trace.cc:993
void disable_I_S_for_this_and_children()
Temporarily disables I_S for this trace and its children.
Definition: opt_trace_context.h:258
void set_query(const char *query, size_t length, const CHARSET_INFO *charset)
Set the "original" query (not transformed, as sent by client) for the current trace.
Definition: opt_trace.cc:1098
Opt_trace_stmt * get_current_stmt_in_gen()
Opt_trace_struct is passed Opt_trace_context*, and needs to know to which statement's trace to attach...
Definition: opt_trace_context.h:245
const Opt_trace_stmt * get_next_stmt_for_I_S(long *got_so_far) const
Definition: opt_trace.cc:1134
feature_value
Features' numeric values for @@optimizer_trace_features variable.
Definition: opt_trace_context.h:202
@ REPEATED_SUBSELECT
Definition: opt_trace_context.h:206
@ RANGE_OPTIMIZER
Definition: opt_trace_context.h:204
@ MISC
Anything unclassified, including the top object (thus, by "inheritance from parent",...
Definition: opt_trace_context.h:217
@ GREEDY_SEARCH
Definition: opt_trace_context.h:203
@ DYNAMIC_RANGE
Definition: opt_trace_context.h:205
~Opt_trace_context()
Definition: opt_trace.cc:793
void reset()
Brainwash: deletes all remembered traces and resets counters regarding OFFSET/LIMIT (so that the next...
Definition: opt_trace.cc:1103
size_t allowed_mem_size_for_current_stmt() const
Compute maximum allowed memory size for current trace.
Definition: opt_trace.cc:1077
static const char * flag_names[]
Names of flags for @@optimizer_trace variable of sys_vars.cc :
Definition: opt_trace_context.h:183
bool support_I_S() const
Definition: opt_trace.cc:988
int I_S_disabled
Dynamically allocated implementation.
Definition: opt_trace_context.h:376
Opt_trace_context()
Definition: opt_trace_context.h:93
bool is_started() const
Returns whether there is a current trace.
Definition: opt_trace_context.h:145
void missing_privilege()
User lacks privileges to see the current trace.
Definition: opt_trace.cc:1118
static const char * feature_names[]
Features' names for @@optimizer_trace_features variable of sys_vars.cc:
Definition: opt_trace_context.h:199
static const feature_value default_features
Optimizer features which are traced by default.
Definition: opt_trace_context.h:230
void restore_I_S()
Restores I_S support to what it was before the previous call to disable_I_S_for_this_and_children().
Definition: opt_trace_context.h:267
Opt_trace_context & operator=(const Opt_trace_context &)
Not defined assignment operator, to disallow assignment.
Opt_trace_context_impl * pimpl
Definition: opt_trace_context.h:369
void end()
Ends the current (=open, unfinished, being-generated) trace.
Definition: opt_trace.cc:946
Opt_trace_context(const Opt_trace_context &)
Not defined copy constructor, to disallow copy.
bool feature_enabled(feature_value f) const
Definition: opt_trace_context.h:236
The trace of one statement.
Definition: opt_trace.cc:110
static constexpr unsigned PSI_INSTRUMENT_ME
Definition: psi_bits.h:42
constexpr bool unlikely(bool expr)
Definition: my_compiler.h:57
Some integer typedefs for easier portability.
unsigned long long int ulonglong
Definition: my_inttypes.h:55
static char * query
Definition: myisam_ftdump.cc:46
const std::string charset("charset")
bool length(const dd::Spatial_reference_system *srs, const Geometry *g1, double *length, bool *null) noexcept
Computes the length of linestrings and multilinestrings.
Definition: length.cc:75
Prealloced_array< Opt_trace_stmt *, 16 > Opt_trace_stmt_array
Definition: opt_trace_context.h:41
Performance schema instrumentation interface.
Definition: m_ctype.h:422