MySQL  8.0.28
Source Code Documentation
Opt_trace_struct Class Reference

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:
Opt_trace_array Opt_trace_object

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_structadd_alnum (const char *key, const char *value)
 Adds a value (of string type) to the structure. More...
 
Opt_trace_structadd_alnum (const char *value)
 Adds a value (of string type) to the structure. More...
 
Opt_trace_structadd_utf8 (const char *key, const char *value, size_t val_length)
 Like add_alnum() but supports any UTF8 characters in 'value'. More...
 
Opt_trace_structadd_utf8 (const char *value, size_t val_length)
 Variant of add_utf8() for adding to an array (no key) More...
 
Opt_trace_structadd_utf8 (const char *key, const char *value)
 Variant of add_utf8() where 'value' is 0-terminated. More...
 
Opt_trace_structadd_utf8 (const char *value)
 Variant of add_utf8() where 'value' is 0-terminated. More...
 
Opt_trace_structadd (const char *key, Item *item)
 Add a value (of Item type) to the structure. More...
 
Opt_trace_structadd (Item *item)
 
Opt_trace_structadd (const char *key, bool value)
 
Opt_trace_structadd (bool value)
 
Opt_trace_structadd (const char *key, int value)
 
Opt_trace_structadd (int value)
 
Opt_trace_structadd (const char *key, uint value)
 
Opt_trace_structadd (uint value)
 
Opt_trace_structadd (const char *key, ulong value)
 
Opt_trace_structadd (ulong value)
 
Opt_trace_structadd (const char *key, longlong value)
 
Opt_trace_structadd (longlong value)
 
Opt_trace_structadd (const char *key, ulonglong value)
 
Opt_trace_structadd (ulonglong value)
 
Opt_trace_structadd (const char *key, double value)
 
Opt_trace_structadd (double value)
 
Opt_trace_structadd_null (const char *key)
 Adds a JSON null object (==Python's "None") More...
 
Opt_trace_structadd_utf8_table (const TABLE_LIST *tab)
 Helper to put the database/table name in an object. More...
 
Opt_trace_structadd_select_number (uint select_number)
 Helper to put the number of query_block in an object. More...
 
Opt_trace_structadd (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_structadd (const char *key, const char *value)
 Not implemented, use add_alnum() instead. More...
 
Opt_trace_structadd (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_structdo_add (const char *key, const char *value, size_t val_length, bool escape)
 Really adds to the object. More...
 
Opt_trace_structdo_add (const char *key, Item *item)
 
Opt_trace_structdo_add (const char *key, bool value)
 
Opt_trace_structdo_add (const char *key, longlong value)
 
Opt_trace_structdo_add (const char *key, ulonglong value)
 
Opt_trace_structdo_add (const char *key, double value)
 
Opt_trace_structdo_add_null (const char *key)
 
Opt_trace_structdo_add_utf8_table (const TABLE_LIST *tab)
 
Opt_trace_structdo_add (const char *key, const Cost_estimate &value)
 
 Opt_trace_struct (const Opt_trace_struct &)
 not defined More...
 
Opt_trace_structoperator= (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_stmtstmt
 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_argOptimizer trace context for this structure
requires_key_argwhether this structure requires/forbids keys for values put inside it (an object requires them, an array forbids them)
keykey 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).
featureoptimizer 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
keykey
costthe 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
keykey
itemthe 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
keykey
valuevalue
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
valuevalue
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_numbernumber 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
keykey
valuevalue
val_lengthlength 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_LIST tab)
inline

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

Parameters
tabTABLE* 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
keykey
valuevalue
val_lengthlength of string 'value'
escapedo 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_LIST 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: