MySQL 8.0.30
Source Code Documentation
Component Services Inventory

This is a group of all component service APIs. More...

Collaboration diagram for Component Services Inventory:

Modules

 Keyring component services
 
 Table Access services
 

Classes

struct  s_mysql_mysql_audit_api_connection
 A service to generate Audit API events of the connection class (MYSQL_AUDIT_CONNECTION_CLASS). More...
 
struct  s_mysql_mysql_audit_api_connection_with_error
 A service to generate Audit API events of the connection class (MYSQL_AUDIT_CONNECTION_CLASS) with the explicitly specified error code value. More...
 
struct  s_mysql_component_sys_variable_register
 Service to register variable and get variable value. More...
 
struct  s_mysql_component_sys_variable_unregister
 Service to unregister variable. More...
 
struct  s_mysql_group_replication_message_service_send
 A service that sends content agnostic messages from a member to the group. More...
 
struct  s_mysql_group_replication_status_service_v1
 A service to get the status of a member of Group Replication. More...
 
struct  s_mysql_host_application_signal
 A service to deliver a signal to host application. More...
 
struct  s_mysql_mysql_keyring_iterator
 Keyring iterator component service definition, which enables to iterate over items stored within currently used keyring. More...
 
struct  s_mysql_mysql_admin_session
 A service to create an "admin" session that's not a subject to max connection count limits. More...
 
struct  s_mysql_mysql_audit_print_service_double_data_source
 Audit print service allows to obtain data of the double type associated with the THD object, which keeps various data of the user session. More...
 
struct  s_mysql_mysql_audit_print_service_longlong_data_source
 Audit print service allows to obtain data of the long long type associated with the THD object, which keeps various data of the user session. More...
 
struct  s_mysql_mysql_authentication_registration
 A service to do registration of fido device. More...
 
struct  s_mysql_mysql_current_thread_reader
 A service to fetch the current thread id. More...
 
struct  s_mysql_mysql_keyring_native_key_id
 A service to read native keybackend id. More...
 
struct  s_mysql_mysql_query_attributes_iterator
 A service to fetch the query attributes for the current thread. More...
 
struct  s_mysql_mysql_query_attribute_string
 A service to fetch the query attribute value as a string. More...
 
struct  s_mysql_mysql_query_attribute_isnull
 A service to fetch the query attribute null flag. More...
 
struct  s_mysql_mysql_system_variable_update_string
 Service to set the global value of system variables. More...
 
struct  s_mysql_mysql_thd_attributes
 THD Attributes service allows to obtain data associated with the THD object, which keeps various attributes of the user session. More...
 
struct  s_mysql_psi_tls_channel_v1
 Service for instrumentation of TLS channel in performance schema. More...
 
struct  s_mysql_reference_caching_channel
 A reference caching channel service. More...
 

Typedefs

typedef struct s_mysql_mysql_audit_api_connection mysql_service_mysql_audit_api_connection_t
 A service to generate Audit API events of the connection class (MYSQL_AUDIT_CONNECTION_CLASS). More...
 
typedef struct s_mysql_mysql_audit_api_connection_with_error mysql_service_mysql_audit_api_connection_with_error_t
 A service to generate Audit API events of the connection class (MYSQL_AUDIT_CONNECTION_CLASS) with the explicitly specified error code value. More...
 
typedef struct s_mysql_component_sys_variable_register mysql_service_component_sys_variable_register_t
 Service to register variable and get variable value. More...
 
typedef struct s_mysql_component_sys_variable_unregister mysql_service_component_sys_variable_unregister_t
 Service to unregister variable. More...
 
typedef struct s_mysql_group_replication_message_service_send mysql_service_group_replication_message_service_send_t
 A service that sends content agnostic messages from a member to the group. More...
 
typedef struct s_mysql_group_replication_status_service_v1 mysql_service_group_replication_status_service_v1_t
 A service to get the status of a member of Group Replication. More...
 
typedef struct s_mysql_host_application_signal mysql_service_host_application_signal_t
 A service to deliver a signal to host application. More...
 
typedef struct s_mysql_mysql_keyring_iterator mysql_service_mysql_keyring_iterator_t
 Keyring iterator component service definition, which enables to iterate over items stored within currently used keyring. More...
 
typedef struct s_mysql_mysql_admin_session mysql_service_mysql_admin_session_t
 A service to create an "admin" session that's not a subject to max connection count limits. More...
 
typedef struct s_mysql_mysql_audit_print_service_double_data_source mysql_service_mysql_audit_print_service_double_data_source_t
 Audit print service allows to obtain data of the double type associated with the THD object, which keeps various data of the user session. More...
 
typedef struct s_mysql_mysql_audit_print_service_longlong_data_source mysql_service_mysql_audit_print_service_longlong_data_source_t
 Audit print service allows to obtain data of the long long type associated with the THD object, which keeps various data of the user session. More...
 
typedef struct s_mysql_mysql_authentication_registration mysql_service_mysql_authentication_registration_t
 A service to do registration of fido device. More...
 
typedef const char * my_h_connection_attributes_iterator
 A service to read the connection attributes from the current session It provides a read-only iterator over the attributes. More...
 
typedef struct s_mysql_mysql_current_thread_reader mysql_service_mysql_current_thread_reader_t
 A service to fetch the current thread id. More...
 
typedef struct s_mysql_mysql_keyring_native_key_id mysql_service_mysql_keyring_native_key_id_t
 A service to read native keybackend id. More...
 
typedef struct s_mysql_mysql_query_attributes_iterator mysql_service_mysql_query_attributes_iterator_t
 A service to fetch the query attributes for the current thread. More...
 
typedef struct s_mysql_mysql_query_attribute_string mysql_service_mysql_query_attribute_string_t
 A service to fetch the query attribute value as a string. More...
 
typedef struct s_mysql_mysql_query_attribute_isnull mysql_service_mysql_query_attribute_isnull_t
 A service to fetch the query attribute null flag. More...
 
typedef struct s_mysql_mysql_system_variable_update_string mysql_service_mysql_system_variable_update_string_t
 Service to set the global value of system variables. More...
 
typedef struct s_mysql_mysql_thd_attributes mysql_service_mysql_thd_attributes_t
 THD Attributes service allows to obtain data associated with the THD object, which keeps various attributes of the user session. More...
 
typedef struct s_mysql_psi_tls_channel_v1 mysql_service_psi_tls_channel_v1_t
 Service for instrumentation of TLS channel in performance schema. More...
 
typedef struct s_mysql_reference_caching_channel mysql_service_reference_caching_channel_t
 A reference caching channel service. More...
 

Detailed Description

This is a group of all component service APIs.

See A Service and a Service Implementation for explanation of what a component service is

Typedef Documentation

◆ my_h_connection_attributes_iterator

A service to read the connection attributes from the current session It provides a read-only iterator over the attributes.

This is some example code to use the iterator:

// at init time. try to reuse the service handles as much as possible
my_service<SERVICE_TYPE(mysql_current_thread_reader)> thd_reader(
"mysql_current_thread_reader", m_reg_srv);
my_service<SERVICE_TYPE(mysql_connection_attributes_iterator)> service(
"mysql_connection_attributes_iterator", m_reg_srv);
if (!service.is_valid() || !thd_reader.is_valid) {
return; //error
}
...
// at parse time
MYSQL_THD thd;
if (thd_reader->get(&thd))
return; //error
const char *charset_string;
const CHARSET_INFO *charset = nullptr;
if (service->init(thd, &iterator)) return; // error
while (!service->get(thd, &iterator, &name.str, &name.length, &value.str,
&value.length, &charset_string)) {
// Do something with name and value
}
service->deinit(iterator);
Wraps my_h_service struct conforming ABI into RAII C++ object with ability to cast to desired service...
Definition: my_service.h:34
const char * my_h_connection_attributes_iterator
A service to read the connection attributes from the current session It provides a read-only iterator...
Definition: mysql_connection_attributes_iterator.h:78
const std::string charset("charset")
#define SERVICE_TYPE(name)
Generates the standard Service type name.
Definition: service.h:75
case opt name
Definition: sslopt-case.h:32
Definition: m_ctype.h:354
Definition: mysql_lex_string.h:39
const char * str
Definition: mysql_lex_string.h:40
size_t length
Definition: mysql_lex_string.h:41

◆ mysql_service_component_sys_variable_register_t

Service to register variable and get variable value.

See also
mysql_component_sys_variable_imp

◆ mysql_service_component_sys_variable_unregister_t

Service to unregister variable.

Make sure to call this for each variable registered.

See also
mysql_service_component_sys_variable_unregister_t

◆ mysql_service_group_replication_message_service_send_t

A service that sends content agnostic messages from a member to the group.

This only works if the component is on a server with group replication running and the member state is ONLINE. If server isn't ONLINE message won't be deliver.

After message sent to all members of the group, all components that have registered group_replication_message_service_recv service will be notified.

SERVICE_TYPE(registry) *plugin_registry = mysql_plugin_registry_acquire();
my_service<SERVICE_TYPE(group_replication_message_service_send)> svc(
"group_replication_message_service_send", plugin_registry);
if (svc.is_valid()) {
bool error = svc->send("tag", "payload", sizeof("payload"));
}
Log error(cerr, "ERROR")
const mysql_service_registry_t * mysql_plugin_registry_acquire()
Returns a new reference to the "registry" service.
Definition: plugin_registry_service.cc:46

◆ mysql_service_group_replication_status_service_v1_t

A service to get the status of a member of Group Replication.

This is only available if the component is on a server with Group Replication plugin installed.

SERVICE_TYPE(registry) *plugin_registry = mysql_plugin_registry_acquire();
my_service<SERVICE_TYPE(group_replication_status_service_v1)> svc(
"group_replication_status_service_v1", plugin_registry);
if (svc.is_valid()) {
bool error = svc->...
}

◆ mysql_service_host_application_signal_t

A service to deliver a signal to host application.

Typically there'll be just one implementation of this by the main application.

Other parties interested in listening to shutdown may override the default implementation with a broadcast one and have multiple implementations receiving the shutdown signal. Or do message queueing to a set of background threads etc.

See also
mysql_component_host_application_signal_imp

◆ mysql_service_mysql_admin_session_t

A service to create an "admin" session that's not a subject to max connection count limits.

This service is an extension to the sessions plugin service suite. The MYSQL_SESSION references are compatible with the plugin service.

See also
mysql_component_mysql_admin_session_imp

◆ mysql_service_mysql_audit_api_connection_t

A service to generate Audit API events of the connection class (MYSQL_AUDIT_CONNECTION_CLASS).

The emit method generates the event in the synchronous way, causing all subscribers to receive it.

See also
mysql_audit_api_connection_imp

◆ mysql_service_mysql_audit_api_connection_with_error_t

A service to generate Audit API events of the connection class (MYSQL_AUDIT_CONNECTION_CLASS) with the explicitly specified error code value.

This service should ONLY be used if we cannot set the THD's Statement Diagnostic Area result code, which is passed along the audit notification chain. The preferred way of generating the event is to rely on THD's internal data as much as possible (mysql_audit_api_connection service)

The emit method generates the event in the synchronous way, causing all subscribers to receive it.

See also
mysql_audit_api_connection_imp

◆ mysql_service_mysql_audit_print_service_double_data_source_t

Audit print service allows to obtain data of the double type associated with the THD object, which keeps various data of the user session.

It also allows to obtain data not necessarily bound with the user session.

Currently, following data is supported:

  • Query time ("query_time") Query execution time [seconds].
  • Rows sent ("rows_sent") Row count sent to the client as a result.
  • Rows examined ("rows_examined") Row count accessed during the query.
  • Bytes received ("bytes_received") Byte count received from the client.
  • Bytes sent ("bytes_sent") Byte count sent to the client.

Initialization

The service can be instantiated using the registry service with the "mysql_audit_print_service_double_data_source" name.

my_service<SERVICE_TYPE(mysql_audit_print_service_double_data_source)>
svc("mysql_audit_print_service_double_data_source", registry);
if (svc.is_valid()) {
// The service is ready to be used
}

Query Time

Query Time represents query execution time in seconds.

double value;
svc->get(m_thd, "query_time", &value);

◆ mysql_service_mysql_audit_print_service_longlong_data_source_t

Audit print service allows to obtain data of the long long type associated with the THD object, which keeps various data of the user session.

It also allows to obtain data not necessarily bound with the user session.

Currently, following data is supported:

  • Query time ("query_time") Query execution time [microseconds].
  • Rows sent ("rows_sent") Row count sent to the client as a result.
  • Rows examined ("rows_examined") Row count accessed during the query.
  • Bytes received ("bytes_received") Byte count received from the client.
  • Bytes sent ("bytes_sent") Byte count sent to the client.

Initialization

The service can be instantiated using the registry service with the "mysql_audit_print_service_double_data_source" name.

my_service<SERVICE_TYPE(mysql_audit_print_service_long_long_data_source)>
svc("mysql_audit_print_service_long_long_data_source", registry);
if (svc.is_valid()) {
// The service is ready to be used
}

Query Time

Query Time represents query execution time in microseconds.

long long value;
svc->get(m_thd, "query_time", &value);

◆ mysql_service_mysql_authentication_registration_t

A service to do registration of fido device.

◆ mysql_service_mysql_current_thread_reader_t

A service to fetch the current thread id.

Use in conjunction with all the related services that operate on thread ids

See also
mysql_component_mysql_current_thread_reader_imp

◆ mysql_service_mysql_keyring_iterator_t

Keyring iterator component service definition, which enables to iterate over items stored within currently used keyring.

my_service<SERVICE_TYPE(mysql_keyring_iterator)> service(
"mysql_keyring_iterator.mysql_server", m_reg_srv);
if (!service.is_valid()) {
return;
}
my_h_keyring_iterator iterator = nullptr;
if (service->init(&iterator)) {
return;
}
char key_id[64];
char user_id[64];
while (iterator != nullptr && service->get(iterator, key_id, sizeof(key_id)
user_id, sizeof(user_id))
== 0) {
// Do something with key and user_id values.
}
service->deinit(iterator);
struct my_h_keyring_iterator_imp * my_h_keyring_iterator
Definition: keyring_iterator_service.h:29

◆ mysql_service_mysql_keyring_native_key_id_t

A service to read native keybackend id.

Typically there'll be just one implementation of this by the main application.

◆ mysql_service_mysql_query_attribute_isnull_t

A service to fetch the query attribute null flag.

Use in conjunction with mysql_query_atrributes_iterator service

See also
mysql_component_mysql_query_attributes_imp

◆ mysql_service_mysql_query_attribute_string_t

A service to fetch the query attribute value as a string.

Use in conjunction with mysql_query_atrributes_iterator service

See also
mysql_component_mysql_query_attributes_imp

◆ mysql_service_mysql_query_attributes_iterator_t

A service to fetch the query attributes for the current thread.

Use in conjunction with all the related services that operate on thread ids

See also
mysql_component_mysql_query_attributes_imp

◆ mysql_service_mysql_system_variable_update_string_t

Service to set the global value of system variables.

This is an example of using the service in an UDF:

if (!make_new_thread &&
mysql_service_mysql_current_thread_reader->get(&thd)) {
*error = 1;
return 0;
}
void *arg1_cs, *arg2_cs;
if (mysql_service_mysql_udf_metadata->argument_get(args, "charset", 1,
&arg1_cs) ||
mysql_service_mysql_udf_metadata->argument_get(args, "charset", 2,
&arg2_cs)) {
*error = 1;
return 0;
}
my_h_string name = nullptr, value = nullptr;
if (mysql_service_mysql_string_converter->convert_from_buffer(
&name, args->args[1], args->lengths[1], ((const char *)arg1_cs)) ||
mysql_service_mysql_string_converter->convert_from_buffer(
&value, args->args[2], args->lengths[2], ((const char *)arg2_cs))) {
if (name) mysql_service_mysql_string_factory->destroy(name);
if (value) mysql_service_mysql_string_factory->destroy(value);
*error = 1;
return 0;
}
if (mysql_service_mysql_system_variable_update_string->set(thd, args->args[3],
nullptr, name, value)) *error = 1;
if (name) mysql_service_mysql_string_factory->destroy(name);
if (value) mysql_service_mysql_string_factory->destroy(value);
#define MYSQL_THD
Definition: backup_page_tracker.h:37
The string functions as a service to the mysql_server component.
Definition: mysql_string_service.cc:45
#define NULL
Definition: types.h:54
See also
mysql_system_variable_update_string_imp

◆ mysql_service_mysql_thd_attributes_t

THD Attributes service allows to obtain data associated with the THD object, which keeps various attributes of the user session.

Currently, following attributes are supported:

  • Query Digest Text

Initialization

The service can be instantiated using the registry service with the "mysql_thd_attributes" name.

my_service<SERVICE_TYPE(mysql_thd_attributes)>
svc("mysql_thd_attributes", registry);
if (svc.is_valid()) {
// The service is ready to be used
}

Digest Text

Query Digest represents converted SQL statement to normalized form. The code below demonstrates how query digest can be obtained from the service.

mysql_thd_attributes->get(m_thd, "query_digest",
reinterpret_cast<void *>(&str));
std::string str(const mysqlrouter::ConfigGenerator::Options::Endpoint &ep)
Definition: config_generator.cc:1055

The buffer can be fetched using the code below:

char buf[1024]; // buffer must be big enough to store the digest
mysql_string_converter->convert_to_buffer(str, buf, sizeof(buf), "utf8mb3");
Definition: buf0block_hint.cc:29

After the string content has been copied into another buffer, it must be destroyed:

mysql_string_factory->destroy(str);

◆ mysql_service_psi_tls_channel_v1_t

Service for instrumentation of TLS channel in performance schema.

◆ mysql_service_reference_caching_channel_t

A reference caching channel service.

The goal of this service is to ensure that event producers spend a MINIMAL amount of time in the emitting code when there are no consumers of the produced events.

Terminology

An event consumer is an implementation of a component service. An event producer is a piece of code that wants to inform all currently registered event consumers about an event. A channel is a device that serves as a singleton of all reference caches for all threads that are to produce events. A reference cache is something each thread producing events must maintain for its lifetime and use it to find the references to event consumers it needs to call.

Typical lifetime of the event consumers

At init time the event consumer will register implementations of any of the services it's interested in receiving notifications for.

Then optionally it might force a channel invalidation to make sure all existing event producers will start sending notifications to it immediately. Or it can just sit and wait for the natural producer's reference cache refresh cycles to kick in.

Now it is receiving notifications from all event producers as they come.

When it wishes to no longer receive notifications it needs to mark itself as invisible for reference cache fill-ins. In this way all reference cache flushes will not pick this implementation up even if it's still registered in the registry.

Eventually all active references will be removed by the natural producers flush cycles. The consumer may choose to expedite this by triggering a channel invalidation.

As with all service implementations, when all references to the services are released it can unload.

Typical lifetime of the event producers

An event producer will usually start at init time by creating channel(s).

Then, for each thread wishing to produce events, a reference cache must be created and maintained until the thread will no longer be producing events.

Now the thread can produce events using the reference cache. This is done by calling the get method and then iterating over the resulting set of references and calling each one in turn as one would normally do for registry service references. It is assumed that the references are owned by the cache and thus they should not be released.

With some cyclical (e.g. at the end of each statement or something) the event producing thread needs to flush the cache. This is to ensure that references to event consumers are not held for very long and that new event consumers are picked up. However flushing the cache is a relatively expensive operation and thus a balance between the number of events produced and the cache being flushed must be achieved.

General remarks

Channels are something each event producer must have to produce events. Channels are to be created by a single thread before the first event is ever produced. And, once created they are to be kept until after the last event is produced.

Channels serve as singletons for caches and you only need one channel instance per event producer component. There usually will be multiple caches (one per event producing thread) per channel.

Creating and destroying a channel is a relatively "expensive" operation that might involve some synchronization and should not be done frequently.

Channels exist to allow a non-related thread to trigger invalidation of all currently active caches on that channel. This is necessary when for example event consumers are registered and are about to be removed.

Invalidating a channel is a thread-safe operation that can be invoked without synchronization at any time.

Each channel is associated with a specific set of service names.

Note
It is a set of service names, not implementation names !

The names are stored and used in event caches to handle all implementations of that particular service.