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_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, so Opt_trace_context must provide this information. More...

const Opt_trace_stmt *	get_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...

UnstructuredTrace *	unstructured_trace ()

void	set_unstructured_trace (UnstructuredTrace *trace)

void	ConsumeUnstructuredTrace (THD *thd)
	Move unstructured trace text (as produced by Hypergraph) into the JSON tree. 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_context &	operator= (const Opt_trace_context &)
	Not defined assignment operator, to disallow assignment. More...

Private Attributes
Opt_trace_context_impl *	pimpl

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

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

◆ ConsumeUnstructuredTrace()

void Opt_trace_context::ConsumeUnstructuredTrace ( THD * thd )

Move unstructured trace text (as produced by Hypergraph) into the JSON tree.

Move unstructured trace text (as used by Hypergraph) into the JSON tree.

◆ 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

f feature

◆ 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_far How 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_all if 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

query	query
length	query's length
charset	charset which was used to encode this query

◆ set_unstructured_trace()

void Opt_trace_context::set_unstructured_trace ( UnstructuredTrace * trace )

inline

◆ 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_S	Whether 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_marker	For 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_line	Should the trace be on a single line without indentation? (More compact for network transfer to programs, less human-readable.)
offset	Offset for restricting trace production.
limit	Limit for restricting trace production.
max_mem_size	Maximum allowed for cumulated size of all remembered traces.
features	Only these optimizer features should be traced.

Return values

false	ok
true	error (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!

◆ unstructured_trace()

UnstructuredTrace * Opt_trace_context::unstructured_trace ( )

inline

Member Data Documentation

◆ default_features

const Opt_trace_context::feature_value Opt_trace_context::default_features

static

Initial value:

=
    Opt_trace_context::feature_value(Opt_trace_context::GREEDY_SEARCH |
                                     Opt_trace_context::RANGE_OPTIMIZER |
                                     Opt_trace_context::DYNAMIC_RANGE |
                                     Opt_trace_context::REPEATED_SUBSELECT)

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}

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",

NullS}

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

"enabled" = tracing enabled
"one_line"= see parameter of Opt_trace_context::start
"default".

◆ 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:

sql/opt_trace_context.h
sql/opt_trace.cc

Classes

Public Types

Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

◆ feature_value

Constructor & Destructor Documentation

◆ Opt_trace_context() [1/2]

◆ ~Opt_trace_context()

◆ Opt_trace_context() [2/2]

Member Function Documentation

◆ allowed_mem_size_for_current_stmt()

◆ ConsumeUnstructuredTrace()

◆ disable_I_S_for_this_and_children()

◆ end()

◆ feature_enabled()

◆ get_current_stmt_in_gen()

◆ get_end_marker()

◆ get_next_stmt_for_I_S()

◆ get_one_line()

◆ is_started()

◆ missing_privilege()

◆ operator=()

◆ purge_stmts()

◆ reset()

◆ restore_I_S()

◆ set_query()

◆ set_unstructured_trace()

◆ start()

◆ support_I_S()

◆ unstructured_trace()

Member Data Documentation

◆ default_features

◆ feature_names

◆ flag_names

◆ I_S_disabled

◆ pimpl