MySQL 9.1.0
Source Code Documentation
s_mysql_component_sys_variable_register Struct Reference

Service to register variable and get variable value. More...

#include <component_sys_var_service.h>

Public Attributes

mysql_service_status_t(* register_variable )(const char *component_name, const char *name, int flags, const char *comment, mysql_sys_var_check_func check, mysql_sys_var_update_func update, void *check_arg, void *variable_value)
 Register a new system variable. More...
 
mysql_service_status_t(* get_variable )(const char *component_name, const char *name, void **val, size_t *out_length_of_val)
 Fetches the global value of a system variable. More...
 

Detailed Description

Service to register variable and get variable value.

See also
mysql_component_sys_variable_imp

Member Data Documentation

◆ get_variable

mysql_service_status_t(* s_mysql_component_sys_variable_register::get_variable) (const char *component_name, const char *name, void **val, size_t *out_length_of_val)

Fetches the global value of a system variable.

Call this to get the global value of a variable. You can access both the component variables (SELECT @global.component_name.variable_name) and the "legacy" system variables (SELECT @global.variable_name) that are registered by the server component. To access the latter you need to pass "mysql_server" (lowercase) as a component name.

A pointer to the value is returned into the val input/output argument. And the length of the value (as applicable) is returned into the out_length_of_val argument.

In case when the user buffer was too small to copy the value, the call fails and needed buffer size is returned by 'out_length_of_val'.

Typical use (char * variable):

char *value, buffer_for_value[160];
size_t value_length;
value= &buffer_for_value[0];
value_length= sizeof(buffer_for_value) - 1;
get_variable("foo", "bar", &value, &value_length);
printf("%.*s", (int) value_length, value);
mysql_service_status_t(* get_variable)(const char *component_name, const char *name, void **val, size_t *out_length_of_val)
Fetches the global value of a system variable.
Definition: component_sys_var_service.h:323
Parameters
component_nameName of the component or "mysql_server" for the legacy ones.
namename of the variable
[in,out]valOn input: a buffer to hold the value. On output a pointer to the value.
[in,out]out_length_of_valOn input: the buffer size. On output the length of the data copied.
Return values
truefailure
falsesuccess

◆ register_variable

mysql_service_status_t(* s_mysql_component_sys_variable_register::register_variable) (const char *component_name, const char *name, int flags, const char *comment, mysql_sys_var_check_func check, mysql_sys_var_update_func update, void *check_arg, void *variable_value)

Register a new system variable.

The variable registered is then accessible in SQL as "SELECT component_name.name" The variable registration needs a global of the relevant type that stores the value.

To define a new variable you need to:

  1. Decide on a variable type among one of the Variable types
  2. Decide on attributes of the type among one of the Variable flags
  3. Declare a local variable placeholder matching the type using one of the Variable macros.
  4. Fill in the placeholder values (min, max, default etc) as appropriate for the selected type.
  5. Provide storage for the variable value: usually a global variable of the relevant type.
  6. Call the function with all of the above to register the system variable.
Warning
: Make sure to unregister the system variable when you no longer intend to have it or when your component deinitializes. Failure to do so will lead to resource leaks and crashes.

Typical use

static int int_variable_value;
static char *str_variable_value;
static ulong enum_variable_value;
static const char *enums[] = {"LOW", "MEDIUM", "STRONG", NullS};
static TYPE_LIB enums_typelib_t = {array_elements(enums) - 1,
"enums_typelib_t",
enums, NULL};
...
INTEGRAL_CHECK_ARG(int) int_arg;
int_arg.def_val = 8;
int_arg.min_val = 0;
int_arg.max_val = 1024;
int_arg.blk_sz = 0;
if (mysql_service_component_sys_variable_register->register_variable(
"foo", "int_sys_var", PLUGIN_VAR_INT,
"Registering int sys_variable", NULL, NULL, (void *)&int_arg,
(void *)&int_variable_value)) {
deal_with_error();
}
STR_CHECK_ARG(str) str_arg;
str_arg.def_val = NULL;
if (mysql_service_component_sys_variable_register->register_variable(
"foo", "str_sys_var", PLUGIN_VAR_STR | PLUGIN_VAR_MEMALLOC,
"Registering string sys_variable", NULL, NULL, (void *)&str_arg,
(void *)&str_variable_value)) {
deal_with_error();
}
ENUM_CHECK_ARG(enum) enum_arg;
enum_arg.def_val = 1; // medium
enum_arg.typelib = &enum_typelib_t;
if (mysql_service_component_sys_variable_register->register_variable(
"foo", "enum_sys_var", PLUGIN_VAR_ENUM,
"Registering enum sys_variable", NULL, NULL, (void *)&enum_arg,
(void *)&enum_variable_value)) {
deal_with_error();
}
#define ENUM_CHECK_ARG(type)
Defines an TYPE_LIB placeholder to fill in with values and pass to the registration function.
Definition: component_sys_var_service.h:147
#define STR_CHECK_ARG(type)
Defines a char * placeholder to fill in with values and pass to the registration function.
Definition: component_sys_var_service.h:170
#define PLUGIN_VAR_MEMALLOC
String needs memory allocated.
Definition: system_variables_bits.h:72
#define PLUGIN_VAR_INT
int variable.
Definition: system_variables_bits.h:40
#define PLUGIN_VAR_STR
char * variable.
Definition: system_variables_bits.h:46
#define PLUGIN_VAR_ENUM
Enum variable.
Definition: system_variables_bits.h:48
if(!(yy_init))
Definition: lexyy.cc:1144
std::string str(const mysqlrouter::ConfigGenerator::Options::Endpoint &ep)
Definition: config_generator.cc:1105
#define NullS
Definition of the null string (a null pointer of type char *), used in some of our string handling co...
Definition: nulls.h:33
A utility class for the ENUM variables.
Definition: component_sys_var_service.h:38
mysql_service_status_t(* register_variable)(const char *component_name, const char *name, int flags, const char *comment, mysql_sys_var_check_func check, mysql_sys_var_update_func update, void *check_arg, void *variable_value)
Register a new system variable.
Definition: component_sys_var_service.h:277
static task_arg int_arg(int i)
Definition: task.h:165
#define NULL
Definition: types.h:55
#define array_elements(A)
Definition: validate_password_imp.cc:50
See also
mysql_service_component_sys_variable_unregister_t
Parameters
component_nameThe name of the component the system variable belongs to.
nameThe name of the variable.
flagsone of Variable types plus zero or more of group_components_services_sys_var_service_flags
commentexplanation of what the variable is to be shown in metadata tables
checkA function to be called to check for validity of the new value.
updateA function to be called when the variable value is updated
check_argThe variable declared through one of Variable
variable_valueA pointer to a storage location of the relevant type.
Return values
trueoperation failed
falseoperation succeeded

The documentation for this struct was generated from the following file: