Object and array are both "structured data" and have lots in common, so the Opt_trace_struct is a base class for them. More...

#include <opt_trace.h>

Inheritance diagram for Opt_trace_struct:

[legend]

Public Member Functions
void	end ()
	The exception to RAII: this function is an explicit way of ending a structure before it goes out of scope. More...

Opt_trace_struct &	add_alnum (const char key, const char value)
	Adds a value (of string type) to the structure. More...

Opt_trace_struct &	add_alnum (const char *value)
	Adds a value (of string type) to the structure. More...

Opt_trace_struct &	add_utf8 (const char key, const char value, size_t val_length)
	Like add_alnum() but supports any UTF8 characters in 'value'. More...

Opt_trace_struct &	add_utf8 (const char *value, size_t val_length)
	Variant of add_utf8() for adding to an array (no key) More...

Opt_trace_struct &	add_utf8 (const char key, const char value)
	Variant of add_utf8() where 'value' is 0-terminated. More...

Opt_trace_struct &	add_utf8 (const char *value)
	Variant of add_utf8() where 'value' is 0-terminated. More...

Opt_trace_struct &	add (const char key, Item item)
	Add a value (of Item type) to the structure. More...

Opt_trace_struct &	add (Item *item)

Opt_trace_struct &	add (const char *key, bool value)

Opt_trace_struct &	add (bool value)

Opt_trace_struct &	add (const char *key, int value)

Opt_trace_struct &	add (int value)

Opt_trace_struct &	add (const char *key, uint value)

Opt_trace_struct &	add (uint value)

Opt_trace_struct &	add (const char *key, ulong value)

Opt_trace_struct &	add (ulong value)

Opt_trace_struct &	add (const char *key, longlong value)

Opt_trace_struct &	add (longlong value)

Opt_trace_struct &	add (const char *key, ulonglong value)

Opt_trace_struct &	add (ulonglong value)

Opt_trace_struct &	add (const char *key, double value)

Opt_trace_struct &	add (double value)

Opt_trace_struct &	add_null (const char *key)
	Adds a JSON null object (==Python's "None") More...

Opt_trace_struct &	add_utf8_table (const Table_ref *tab)
	Helper to put the database/table name in an object. More...

Opt_trace_struct &	add_select_number (uint select_number)
	Helper to put the number of query_block in an object. More...

Opt_trace_struct &	add (const char *key, const Cost_estimate &cost)
	Add a value to the structure. More...

bool	set_not_empty ()
	Informs this structure that we are adding data (scalars, structures) to it. More...

const char *	check_key (const char *key)
	Validates the key about to be added. More...

Protected Member Functions
	Opt_trace_struct (Opt_trace_context ctx_arg, bool requires_key_arg, const char key, Opt_trace_context::feature_value feature)

	~Opt_trace_struct ()

Private Member Functions
Opt_trace_struct &	add (const char key, const char value)
	Not implemented, use add_alnum() instead. More...

Opt_trace_struct &	add (const char *key)

void	do_construct (Opt_trace_context ctx, bool requires_key, const char key, Opt_trace_context::feature_value feature)
	Full initialization. More...

void	do_destruct ()
	Really does destruction. More...

Opt_trace_struct &	do_add (const char key, const char value, size_t val_length, bool escape)
	Really adds to the object. More...

Opt_trace_struct &	do_add (const char key, Item item)

Opt_trace_struct &	do_add (const char *key, bool value)

Opt_trace_struct &	do_add (const char *key, longlong value)

Opt_trace_struct &	do_add (const char *key, ulonglong value)

Opt_trace_struct &	do_add (const char *key, double value)

Opt_trace_struct &	do_add_null (const char *key)

Opt_trace_struct &	do_add_utf8_table (const Table_ref *tab)

Opt_trace_struct &	do_add (const char *key, const Cost_estimate &value)

	Opt_trace_struct (const Opt_trace_struct &)
	not defined More...

Opt_trace_struct &	operator= (const Opt_trace_struct &)
	not defined More...

Private Attributes
bool	started
	Whether the structure does tracing or is dummy. More...

bool	requires_key
	Whether the structure requires/forbids keys for values inside it. More...

bool	has_disabled_I_S
	Whether this structure caused tracing to be disabled in this statement because belonging to a not-traced optimizer feature, in accordance with the value of @@optimizer_trace_features. More...

bool	empty

Opt_trace_stmt *	stmt
	Trace owning the structure. More...

const char *	saved_key
	Key if the structure is the value of a key/value pair, NULL otherwise. More...

char	previous_key [25]
	Fixed-length prefix of previous key in this structure, if this structure is an object. More...

Detailed Description

Object and array are both "structured data" and have lots in common, so the Opt_trace_struct is a base class for them.

When you want to add a structure to the trace, you create an instance of Opt_trace_object or Opt_trace_array, then you add information to it with add(), then the destructor closes the structure (we use RAII, Resource Acquisition Is Initialization).

Constructor & Destructor Documentation

◆ Opt_trace_struct() [1/2]

Opt_trace_struct::Opt_trace_struct	(	Opt_trace_context *	ctx_arg,
		bool	requires_key_arg,
		const char *	key,
		Opt_trace_context::feature_value	feature
	)

inlineprotected

Parameters

ctx_arg	Optimizer trace context for this structure
requires_key_arg	whether this structure requires/forbids keys for values put inside it (an object requires them, an array forbids them)
key	key if this structure is the value of a key/value pair, NULL otherwise. This pointer must remain constant and valid until the object is destroyed (to support saved_key).
feature	optimizer feature to which this structure belongs

This constructor is never called directly, only from subclasses.

◆ ~Opt_trace_struct()

Opt_trace_struct::~Opt_trace_struct ( )

inlineprotected

◆ Opt_trace_struct() [2/2]

Opt_trace_struct::Opt_trace_struct ( const Opt_trace_struct & )

private

not defined

Member Function Documentation

◆ add() [1/19]

Opt_trace_struct & Opt_trace_struct::add ( bool value )

inline

◆ add() [2/19]

Opt_trace_struct & Opt_trace_struct::add ( const char * key )

private

◆ add() [3/19]

Opt_trace_struct & Opt_trace_struct::add	(	const char *	key,
		bool	value
	)

inline

◆ add() [4/19]

Opt_trace_struct & Opt_trace_struct::add	(	const char *	key,
		const char *	value
	)

private

Not implemented, use add_alnum() instead.

◆ add() [5/19]

Opt_trace_struct & Opt_trace_struct::add	(	const char *	key,
		const Cost_estimate &	cost
	)

inline

Add a value to the structure.

Parameters

key	key
cost	the value of Cost_estimate

Returns: a reference to the structure

◆ add() [6/19]

Opt_trace_struct & Opt_trace_struct::add	(	const char *	key,
		double	value
	)

inline

◆ add() [7/19]

Opt_trace_struct & Opt_trace_struct::add	(	const char *	key,
		int	value
	)

inline

◆ add() [8/19]

Opt_trace_struct & Opt_trace_struct::add	(	const char *	key,
		Item *	item
	)

inline

Add a value (of Item type) to the structure.

The Item should be a condition (like a WHERE clause) which will be pretty-printed into the trace. This is useful for showing condition transformations (equality propagation etc).

Parameters

key	key
item	the Item

Returns: a reference to the structure

◆ add() [9/19]

Opt_trace_struct & Opt_trace_struct::add	(	const char *	key,
		longlong	value
	)

inline

◆ add() [10/19]

Opt_trace_struct & Opt_trace_struct::add	(	const char *	key,
		uint	value
	)

inline

◆ add() [11/19]

Opt_trace_struct & Opt_trace_struct::add	(	const char *	key,
		ulong	value
	)

inline

◆ add() [12/19]

Opt_trace_struct & Opt_trace_struct::add	(	const char *	key,
		ulonglong	value
	)

inline

◆ add() [13/19]

Opt_trace_struct & Opt_trace_struct::add ( double value )

inline

◆ add() [14/19]

Opt_trace_struct & Opt_trace_struct::add ( int value )

inline

◆ add() [15/19]

Opt_trace_struct & Opt_trace_struct::add ( Item * item )

inline

◆ add() [16/19]

Opt_trace_struct & Opt_trace_struct::add ( longlong value )

inline

◆ add() [17/19]

Opt_trace_struct & Opt_trace_struct::add ( uint value )

inline

◆ add() [18/19]

Opt_trace_struct & Opt_trace_struct::add ( ulong value )

inline

◆ add() [19/19]

Opt_trace_struct & Opt_trace_struct::add ( ulonglong value )

inline

◆ add_alnum() [1/2]

Opt_trace_struct & Opt_trace_struct::add_alnum	(	const char *	key,
		const char *	value
	)

inline

Adds a value (of string type) to the structure.

A key is specified, so it adds the key/value pair (the structure must thus be an object).

There are two "add_*" variants to add a string value. If the value is 0-terminated and each character

is ASCII 7-bit
has ASCII code >=32 and is neither '"' nor '\' then add_alnum() should be used. That should be the case for all fixed strings like add_alnum("cause", "cost"). Otherwise, add_utf8() should be used; it accepts any UTF8-encoded character in 'value' and will escape characters which JSON requires (and is thus slower than add_alnum()). It should be used for all strings which we get from the server's objects (indeed a table's name, a WHERE condition, may contain "strange" characters).

Parameters

key	key
value	value

Returns

a reference to the structure, useful for chaining like this:

add(x,y).add(z,t).add(u,v)

String-related add() variants are named add_[something]():

to avoid confusing the compiler between: add(const char *value, size_t val_length) and add(const char *key, ulonglong value)
and because String::length() returns uint32 and not size_t, so for add(str.ptr(), str.length()) compiler may pick add(const char *key, double value) instead of add(const char *value, size_t val_length).

◆ add_alnum() [2/2]

Opt_trace_struct & Opt_trace_struct::add_alnum ( const char * value )

inline

Adds a value (of string type) to the structure.

No key is specified, so it adds only the value (the structure must thus be an array).

Parameters

value value

Returns: a reference to the structure

◆ add_null()

Opt_trace_struct & Opt_trace_struct::add_null ( const char * key )

inline

Adds a JSON null object (==Python's "None")

◆ add_select_number()

Opt_trace_struct & Opt_trace_struct::add_select_number ( uint select_number )

inline

Helper to put the number of query_block in an object.

Parameters

select_number number of query_block

◆ add_utf8() [1/4]

Opt_trace_struct & Opt_trace_struct::add_utf8	(	const char *	key,
		const char *	value
	)

inline

Variant of add_utf8() where 'value' is 0-terminated.

◆ add_utf8() [2/4]

Opt_trace_struct & Opt_trace_struct::add_utf8	(	const char *	key,
		const char *	value,
		size_t	val_length
	)

inline

Like add_alnum() but supports any UTF8 characters in 'value'.

Will "escape" 'value' to be JSON-compliant.

Parameters

key	key
value	value
val_length	length of string 'value'

◆ add_utf8() [3/4]

Opt_trace_struct & Opt_trace_struct::add_utf8 ( const char * value )

inline

Variant of add_utf8() where 'value' is 0-terminated.

◆ add_utf8() [4/4]

Opt_trace_struct & Opt_trace_struct::add_utf8	(	const char *	value,
		size_t	val_length
	)

inline

Variant of add_utf8() for adding to an array (no key)

◆ add_utf8_table()

Opt_trace_struct & Opt_trace_struct::add_utf8_table ( const Table_ref * tab )

inline

Helper to put the database/table name in an object.

Parameters

tab	TABLE* pointer

◆ check_key()

const char * Opt_trace_struct::check_key ( const char * key )

Validates the key about to be added.

Note: this is reserved for use by Opt_trace_stmt.

When adding a value (or array or object) to an array, or a key/value pair to an object, we need to know this outer array or object.

It would be possible, when trying to add a key to an array, which is wrong in JSON, or similarly when trying to add a value without any key to an object, to catch it at compilation time, if the adder received, as function parameter, the type of the structure (like Opt_trace_array*). Then the add(key,val) call would not compile as Opt_trace_array wouldn't feature it.

But as explained in comment of class Opt_trace_context we cannot pass down the object, have to maintain a "current object or array" in the Opt_trace_context context (pointer to an instance of Opt_trace_struct), and the adder grabs it from the context.

As this current structure is of type "object or array", we cannot do compile-time checks that only suitable functions are used. A call to add(key,value) is necessarily legal for the compiler as the structure may be an object, though it will be wrong in case the structure is actually an array at run-time. Thus we have the risk of an untested particular situation where the current structure is not an object (but an array) though the code expected it to be one. This happens in practice, because subqueries are evaluated in many possible places of code, not all of them being known. Same happens, to a lesser extent, with calls to the range optimizer. So at run-time, in check_key(), we detect wrong usage, like adding a value to an object without specifying a key, and then remove the unnecessary key, or add an autogenerated key.

◆ do_add() [1/7]

Opt_trace_struct & Opt_trace_struct::do_add	(	const char *	key,
		bool	value
	)

private

◆ do_add() [2/7]

Opt_trace_struct & Opt_trace_struct::do_add	(	const char *	key,
		const char *	value,
		size_t	val_length,
		bool	escape
	)

private

Really adds to the object.

See also: add().

Note: add() has an up-front if(), hopefully inlined, so that in the common case - tracing run-time disabled - we have no function call. If tracing is enabled, we call do_add(). In a 20-table plan search (as in BUG#50595), the execution time was decreased from 2.6 to 2.0 seconds thanks to this inlined-if trick.

Parameters

key	key
value	value
val_length	length of string 'value'
escape	do JSON-compliant escaping of 'value'. If 'escape' is false, 'value' should be ASCII. Otherwise, should be UTF8.

◆ do_add() [3/7]

Opt_trace_struct & Opt_trace_struct::do_add	(	const char *	key,
		const Cost_estimate &	value
	)

private

◆ do_add() [4/7]

Opt_trace_struct & Opt_trace_struct::do_add	(	const char *	key,
		double	value
	)

private

◆ do_add() [5/7]

Opt_trace_struct & Opt_trace_struct::do_add	(	const char *	key,
		Item *	item
	)

private

◆ do_add() [6/7]

Opt_trace_struct & Opt_trace_struct::do_add	(	const char *	key,
		longlong	value
	)

private

◆ do_add() [7/7]

Opt_trace_struct & Opt_trace_struct::do_add	(	const char *	key,
		ulonglong	value
	)

private

◆ do_add_null()

Opt_trace_struct & Opt_trace_struct::do_add_null ( const char * key )

private

◆ do_add_utf8_table()

Opt_trace_struct & Opt_trace_struct::do_add_utf8_table ( const Table_ref * tab )

private

◆ do_construct()

void Opt_trace_struct::do_construct	(	Opt_trace_context *	ctx,
		bool	requires_key,
		const char *	key,
		Opt_trace_context::feature_value	feature
	)

private

Full initialization.

See also: Opt_trace_struct::Opt_trace_struct

◆ do_destruct()

void Opt_trace_struct::do_destruct ( )

private

Really does destruction.

◆ end()

void Opt_trace_struct::end ( void )

inline

The exception to RAII: this function is an explicit way of ending a structure before it goes out of scope.

Don't use it unless RAII mandates a new scope which mandates re-indenting lots of code lines.

◆ operator=()

Opt_trace_struct & Opt_trace_struct::operator= ( const Opt_trace_struct & )

private

not defined

◆ set_not_empty()

bool Opt_trace_struct::set_not_empty ( )

inline

Informs this structure that we are adding data (scalars, structures) to it.

This is used only if sending to I_S.

Returns: whether the structure was empty so far.

Note: this is reserved for use by Opt_trace_stmt.

Member Data Documentation

◆ empty

bool Opt_trace_struct::empty

private

See also: set_not_empty()

◆ has_disabled_I_S

bool Opt_trace_struct::has_disabled_I_S

private

Whether this structure caused tracing to be disabled in this statement because belonging to a not-traced optimizer feature, in accordance with the value of @@optimizer_trace_features.

◆ previous_key

char Opt_trace_struct::previous_key[25]

private

Fixed-length prefix of previous key in this structure, if this structure is an object.

Serves to detect when adding two same consecutive keys to an object, which would be wrong.

◆ requires_key

bool Opt_trace_struct::requires_key

private

Whether the structure requires/forbids keys for values inside it.

true: this is an object. false: this is an array.

Note: The canonical way would be to not have such bool per instance, but rather have a pure virtual member function Opt_trace_struct::requires_key(), overloaded by Opt_trace_object (returning true) and by Opt_trace_array (returning false). But Opt_trace_object::requires_key() would not be accessible from Opt_trace_struct::do_construct() (which would complicate coding), whereas the bool is.

◆ saved_key

const char* Opt_trace_struct::saved_key

private

Key if the structure is the value of a key/value pair, NULL otherwise.

◆ started

bool Opt_trace_struct::started

private

Whether the structure does tracing or is dummy.

◆ stmt

Opt_trace_stmt* Opt_trace_struct::stmt

private

Trace owning the structure.

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

sql/opt_trace.h
sql/opt_trace.cc

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Opt_trace_struct() [1/2]

◆ ~Opt_trace_struct()

◆ Opt_trace_struct() [2/2]

Member Function Documentation

◆ add() [1/19]

◆ add() [2/19]

◆ add() [3/19]

◆ add() [4/19]

◆ add() [5/19]

◆ add() [6/19]

◆ add() [7/19]

◆ add() [8/19]

◆ add() [9/19]

◆ add() [10/19]

◆ add() [11/19]

◆ add() [12/19]

◆ add() [13/19]

◆ add() [14/19]

◆ add() [15/19]

◆ add() [16/19]

◆ add() [17/19]

◆ add() [18/19]

◆ add() [19/19]

◆ add_alnum() [1/2]

◆ add_alnum() [2/2]

◆ add_null()

◆ add_select_number()

◆ add_utf8() [1/4]

◆ add_utf8() [2/4]

◆ add_utf8() [3/4]

◆ add_utf8() [4/4]

◆ add_utf8_table()

◆ check_key()

◆ do_add() [1/7]

◆ do_add() [2/7]

◆ do_add() [3/7]

◆ do_add() [4/7]

◆ do_add() [5/7]

◆ do_add() [6/7]

◆ do_add() [7/7]

◆ do_add_null()

◆ do_add_utf8_table()

◆ do_construct()

◆ do_destruct()

◆ end()

◆ operator=()

◆ set_not_empty()

Member Data Documentation

◆ empty

◆ has_disabled_I_S

◆ previous_key

◆ requires_key

◆ saved_key

◆ started

◆ stmt