MySQL 8.3.0
Source Code Documentation
Opt_trace_context Class Reference

A per-session context which is always available at any point of execution, because in practice it's accessible from THD which contains: More...

#include <opt_trace_context.h>

Classes

class  Opt_trace_context_impl
 To have the smallest impact on THD's size, most of the implementation is moved to a separate class Opt_trace_context_impl which is instantiated on the heap when really needed. More...
 

Public Types

enum  { FLAG_DEFAULT = 0 , FLAG_ENABLED = 1 << 0 , FLAG_ONE_LINE = 1 << 1 }
 Flags' numeric values for @@optimizer_trace variable. More...
 
enum  feature_value {
  GREEDY_SEARCH = 1 << 0 , RANGE_OPTIMIZER = 1 << 1 , DYNAMIC_RANGE = 1 << 2 , REPEATED_SUBSELECT = 1 << 3 ,
  MISC = 1 << 7
}
 Features' numeric values for @@optimizer_trace_features variable. More...
 

Public Member Functions

 Opt_trace_context ()
 
 ~Opt_trace_context ()
 
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. More...
 
void end ()
 Ends the current (=open, unfinished, being-generated) trace. More...
 
bool is_started () const
 Returns whether there is a current trace. More...
 
bool support_I_S () const
 
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. More...
 
void reset ()
 Brainwash: deletes all remembered traces and resets counters regarding OFFSET/LIMIT (so that the next statement is considered as "at offset 0"). More...
 
bool get_end_marker () const
 
bool get_one_line () const
 
void missing_privilege ()
 User lacks privileges to see the current trace. More...
 
bool feature_enabled (feature_value f) const
 
Opt_trace_stmtget_current_stmt_in_gen ()
 Opt_trace_struct is passed Opt_trace_context*, and needs to know to which statement's trace to attach, so Opt_trace_context must provide this information. More...
 
const Opt_trace_stmtget_next_stmt_for_I_S (long *got_so_far) const
 
void disable_I_S_for_this_and_children ()
 Temporarily disables I_S for this trace and its children. More...
 
void restore_I_S ()
 Restores I_S support to what it was before the previous call to disable_I_S_for_this_and_children(). More...
 

Static Public Attributes

static const char * flag_names []
 Names of flags for @@optimizer_trace variable of sys_vars.cc : More...
 
static const char * feature_names []
 Features' names for @@optimizer_trace_features variable of sys_vars.cc: More...
 
static const feature_value default_features
 Optimizer features which are traced by default. More...
 

Private Member Functions

void purge_stmts (bool purge_all)
 Find and delete unneeded traces. More...
 
size_t allowed_mem_size_for_current_stmt () const
 Compute maximum allowed memory size for current trace. More...
 
 Opt_trace_context (const Opt_trace_context &)
 Not defined copy constructor, to disallow copy. More...
 
Opt_trace_contextoperator= (const Opt_trace_context &)
 Not defined assignment operator, to disallow assignment. More...
 

Private Attributes

Opt_trace_context_implpimpl
 
int I_S_disabled
 Dynamically allocated implementation. More...
 

Detailed Description

A per-session context which is always available at any point of execution, because in practice it's accessible from THD which contains:

Opt_trace_context opt_trace; 

It maintains properties of the session's regarding tracing: enabled/disabled state, style (all trace on one line, or not, etc), a list of all remembered traces of previous and current SQL statement (as restricted by OFFSET/LIMIT), and a pointer to the current (being-generated) trace (which itself has a pointer to its current open object/array).

Here is why the context needs to provide the current open object/array:

  • When adding a value (scalar or array or object) to an array, or adding a key/value pair to an object, we need this outer object or array (from now on, we will use the term "structure" for "object or array", as both are structured types).
  • The most natural way would be that the outer object would be passed in argument to the adder (the function which wants to add the value or key/value).
  • But tracing is sometimes produced from deep down the stack trace, with many intermediate frames doing no tracing (writing nothing to the trace), so it would require passing the outer structure through many levels, thus modifying many function prototypes. Example (in gdb "backtrace" notation: inner frames first):
        #0  Item_in_subselect::single_value_transformer
            - opens an object for key "transformation"
        #1  Item_in_subselect::select_in_like_transformer - does no tracing
        #2  Item_allany_subselect::select_transformer - does no tracing
        #3  Query_block::prepare - opens an object for key "join_preparation"
    
    So the object opened in #3 would have to be passed in argument to #2 and #1 in order to finally reach #0 where object "transformation" would be added to it.
  • So, as we cannot practically pass the object down, we rather maintain a "current object or array" accessible from the Opt_trace_context context; it's a pointer to an instance of Opt_trace_struct, and the function deep down (frame #0) grabs it from the context, where it was depositted by the function high up (frame #3 in the last example).

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Flags' numeric values for @@optimizer_trace variable.

Enumerator
FLAG_DEFAULT 
FLAG_ENABLED 
FLAG_ONE_LINE 

◆ feature_value

Features' numeric values for @@optimizer_trace_features variable.

Enumerator
GREEDY_SEARCH 
RANGE_OPTIMIZER 
DYNAMIC_RANGE 
REPEATED_SUBSELECT 
MISC 

Anything unclassified, including the top object (thus, by "inheritance from parent", disabling MISC makes an empty trace).

This feature cannot be disabled by the user; for this it is important that it always has biggest flag; flag's value itself does not matter.

Constructor & Destructor Documentation

◆ Opt_trace_context() [1/2]

Opt_trace_context::Opt_trace_context ( )
inline

◆ ~Opt_trace_context()

Opt_trace_context::~Opt_trace_context ( )

◆ Opt_trace_context() [2/2]

Opt_trace_context::Opt_trace_context ( const Opt_trace_context )
private

Not defined copy constructor, to disallow copy.

Member Function Documentation

◆ allowed_mem_size_for_current_stmt()

size_t Opt_trace_context::allowed_mem_size_for_current_stmt ( ) const
private

Compute maximum allowed memory size for current trace.

The current trace is the only one active. Other traces break down in two groups:

  • the finished ones (from previously executed statements),
  • the "started but not finished ones": they are not current, are not being updated at this moment: this must be the trace of a top statement calling a substatement which is the current trace now: trace's top statement is not being updated at this moment. So the current trace can grow in the room left by all traces above.

◆ disable_I_S_for_this_and_children()

void Opt_trace_context::disable_I_S_for_this_and_children ( )
inline

Temporarily disables I_S for this trace and its children.

◆ end()

void Opt_trace_context::end ( void  )

Ends the current (=open, unfinished, being-generated) trace.

If missing_privilege() has been called between start() and end(), end() restores I_S support to what it was before the call to missing_privilege(). This is the key to ensure that missing_privilege() does not disable I_S support for the rest of the connection's life!

◆ feature_enabled()

bool Opt_trace_context::feature_enabled ( feature_value  f) const
inline
Returns
whether an optimizer feature should be traced.
Parameters
ffeature

◆ get_current_stmt_in_gen()

Opt_trace_stmt * Opt_trace_context::get_current_stmt_in_gen ( )
inline

Opt_trace_struct is passed Opt_trace_context*, and needs to know to which statement's trace to attach, so Opt_trace_context must provide this information.

◆ get_end_marker()

bool Opt_trace_context::get_end_marker ( ) const
inline
See also
parameters of Opt_trace_context::start()

◆ get_next_stmt_for_I_S()

const Opt_trace_stmt * Opt_trace_context::get_next_stmt_for_I_S ( long *  got_so_far) const
Returns
the next statement to show in I_S.
Parameters
[in,out]got_so_farHow many statements the caller got so far (by previous calls to this function); function updates this count.
Note
traces are returned from oldest to newest.

◆ get_one_line()

bool Opt_trace_context::get_one_line ( ) const
inline
See also
parameters of Opt_trace_context::start()

◆ is_started()

bool Opt_trace_context::is_started ( ) const
inline

Returns whether there is a current trace.

◆ missing_privilege()

void Opt_trace_context::missing_privilege ( )

User lacks privileges to see the current trace.

Make the trace appear empty in Opt_trace_info, and disable I_S for all its upcoming children.

Once a call to this function has been made, subsequent calls to it before end() have no effects.

◆ operator=()

Opt_trace_context & Opt_trace_context::operator= ( const Opt_trace_context )
private

Not defined assignment operator, to disallow assignment.

◆ purge_stmts()

void Opt_trace_context::purge_stmts ( bool  purge_all)
private

Find and delete unneeded traces.

For example if OFFSET=-1,LIMIT=1, only the last trace is needed. When a new trace is started, the previous traces becomes unneeded and this function deletes them which frees memory.

Parameters
purge_allif true, ignore OFFSET and thus delete everything

◆ reset()

void Opt_trace_context::reset ( void  )

Brainwash: deletes all remembered traces and resets counters regarding OFFSET/LIMIT (so that the next statement is considered as "at offset 0").

Does not reset the @@optimizer_trace_offset/limit variables.

◆ restore_I_S()

void Opt_trace_context::restore_I_S ( )
inline

Restores I_S support to what it was before the previous call to disable_I_S_for_this_and_children().

◆ set_query()

void Opt_trace_context::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.

Parameters
queryquery
lengthquery's length
charsetcharset which was used to encode this query

◆ start()

bool Opt_trace_context::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.

Parameters
support_I_SWhether this statement should have its trace in information_schema
support_dbug_or_missing_priv'true' if this statement should have its trace in the dbug log (–debug), or if missing_privilege() may be called on this trace
end_markerFor a key/(object|array) pair, should the key be repeated in a comment when the object|array closes? like
                         "key_foo": {
                                      multi-line blah
                                    } / * key_foo * /
This is for human-readability only, not valid in JSON. Note that YAML supports #-prefixed comments (we would just need to put the next item's "," before the current item's "#").
one_lineShould the trace be on a single line without indentation? (More compact for network transfer to programs, less human-readable.)
offsetOffset for restricting trace production.
limitLimit for restricting trace production.
max_mem_sizeMaximum allowed for cumulated size of all remembered traces.
featuresOnly these optimizer features should be traced.
Return values
falseok
trueerror (OOM): instance is unusable, so only destructor is permitted on it; any other member function has undefined effects.

◆ support_I_S()

bool Opt_trace_context::support_I_S ( ) const
Returns
whether the current trace writes to I_S. This function should rarely be used. Don't you use this for some clever optimizations bypassing opt trace!

Member Data Documentation

◆ default_features

const Opt_trace_context::feature_value Opt_trace_context::default_features
static
Initial value:
=
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
@ GREEDY_SEARCH
Definition: opt_trace_context.h:203
@ DYNAMIC_RANGE
Definition: opt_trace_context.h:205

Optimizer features which are traced by default.

◆ feature_names

const char * Opt_trace_context::feature_names
static
Initial value:
= {
"greedy_search", "range_optimizer", "dynamic_range",
"repeated_subselect", "default", NullS}
#define NullS
Definition of the null string (a null pointer of type char *), used in some of our string handling co...
Definition: nulls.h:32

Features' names for @@optimizer_trace_features variable of sys_vars.cc:

  • "greedy_search" = the greedy search for a plan
  • "range_optimizer" = the cost analysis of accessing data through ranges in indexes
  • "dynamic_range" = the range optimization performed for each record when access method is dynamic range
  • "repeated_subselect" = the repeated execution of subselects
  • "default".

◆ flag_names

const char * Opt_trace_context::flag_names
static
Initial value:
= {"enabled", "one_line", "default",

Names of flags for @@optimizer_trace variable of sys_vars.cc :

◆ I_S_disabled

int Opt_trace_context::I_S_disabled
private

Dynamically allocated implementation.

<>0 <=> any to-be-created statement's trace should not be in information_schema. This applies to next statements, their substatements, etc.

◆ pimpl

Opt_trace_context_impl* Opt_trace_context::pimpl
private

The documentation for this class was generated from the following files: