The server plugin interface enables plugins to expose status and system variables using thestatus_vars andsystem_vars members of the general plugin descriptor.
Thestatus_vars member of the general plugin descriptor, if not 0, points to an array ofst_mysql_show_var structures, each of which describes one status variable, followed by a structure with all members set to 0. Thest_mysql_show_var structure has this definition:
struct st_mysql_show_var { const char *name; char *value; enum enum_mysql_show_type type;}; The following table shows the permissible status variabletype values and what the corresponding variable should be.
Table 4.1 Server Plugin Status Variable Types
| Variable Type | Meaning |
|---|---|
SHOW_BOOL | Pointer to a boolean variable |
SHOW_INT | Pointer to an integer variable |
SHOW_LONG | Pointer to a long integer variable |
SHOW_LONGLONG | Pointer to a longlong integer variable |
SHOW_CHAR | A string |
SHOW_CHAR_PTR | Pointer to a string |
SHOW_ARRAY | Pointer to anotherst_mysql_show_var array |
SHOW_FUNC | Pointer to a function |
SHOW_DOUBLE | Pointer to a double |
For theSHOW_FUNC type, the function is called and fills in itsout parameter, which then provides information about the variable to be displayed. The function has this signature:
#define SHOW_VAR_FUNC_BUFF_SIZE 1024typedef int (*mysql_show_var_func) (void *thd, struct st_mysql_show_var *out, char *buf); Thesystem_vars member, if not 0, points to an array ofst_mysql_sys_var structures, each of which describes one system variable (which can also be set from the command-line or configuration file), followed by a structure with all members set to 0. Thest_mysql_sys_var structure is defined as follows:
struct st_mysql_sys_var { int flags; const char *name, *comment; int (*check)(THD*, struct st_mysql_sys_var *, void*, st_mysql_value*); void (*update)(THD*, struct st_mysql_sys_var *, void*, const void*);};Additional fields are append as required depending upon the flags.
For convenience, a number of macros are defined that make creating new system variables within a plugin much simpler.
Throughout the macros, the following fields are available:
name: An unquoted identifier for the system variable.varname: The identifier for the static variable. Where not available, it is the same as thenamefield.opt: Additional use flags for the system variable. The following table shows the permissible flags.Table 4.2 Server Plugin System Variable Flags
Flag Value Description PLUGIN_VAR_READONLYThe system variable is read only PLUGIN_VAR_NOSYSVARThe system variable is not user visible at runtime PLUGIN_VAR_NOCMDOPTThe system variable is not configurable from the command line PLUGIN_VAR_NOCMDARGNo argument is required at the command line (typically used for boolean variables) PLUGIN_VAR_RQCMDARGAn argument is required at the command line (this is the default) PLUGIN_VAR_OPCMDARGAn argument is optional at the command line PLUGIN_VAR_MEMALLOCUsed for string variables; indicates that memory is to be allocated for storage of the string comment: A descriptive comment to be displayed in the server help message.NULLif this variable is to be hidden.check: The check function,NULLfor default.update: The update function,NULLfor default.default: The variable default value.minimum: The variable minimum value.maximum: The variable maximum value.blocksize: The variable block size. When the value is set, it is rounded to the nearest multiple ofblocksize.
A system variable may be accessed either by using the static variable directly or by using theSYSVAR()accessor macro. TheSYSVAR() macro is provided for completeness. Usually it should be used only when the code cannot directly access the underlying variable.
For example:
static int my_foo;static MYSQL_SYSVAR_INT(foo_var, my_foo, PLUGIN_VAR_RQCMDARG, "foo comment", NULL, NULL, 0, 0, INT_MAX, 0); ... SYSVAR(foo_var)= value; value= SYSVAR(foo_var); my_foo= value; value= my_foo; Session variables may be accessed only through theTHDVAR() accessor macro. For example:
static MYSQL_THDVAR_BOOL(some_flag, PLUGIN_VAR_NOCMDARG, "flag comment", NULL, NULL, FALSE); ... if (THDVAR(thd, some_flag)) { do_something(); THDVAR(thd, some_flag)= FALSE; } All global and session system variables must be published tomysqld before use. This is done by constructing aNULL-terminated array of the variables and linking to it in the plugin public interface. For example:
static struct st_mysql_sys_var *my_plugin_vars[]= { MYSQL_SYSVAR(foo_var), MYSQL_SYSVAR(some_flag), NULL};mysql_declare_plugin(fooplug){ MYSQL_..._PLUGIN, &plugin_data, "fooplug", "foo author", "This does foo!", PLUGIN_LICENSE_GPL, foo_init, foo_fini, 0x0001, NULL, my_plugin_vars, NULL, 0}mysql_declare_plugin_end;The following convenience macros enable you to declare different types of system variables:
Boolean system variables of type
bool, which is a 1-byte boolean. (0 =false, 1 =true)MYSQL_THDVAR_BOOL(name, opt, comment, check, update, default)MYSQL_SYSVAR_BOOL(name, varname, opt, comment, check, update, default)String system variables of type
char*, which is a pointer to a null-terminated string.MYSQL_THDVAR_STR(name, opt, comment, check, update, default)MYSQL_SYSVAR_STR(name, varname, opt, comment, check, update, default)Integer system variables, of which there are several varieties.
An
intsystem variable, which is typically a 4-byte signed word.MYSQL_THDVAR_INT(name, opt, comment, check, update, default, min, max, blk)MYSQL_SYSVAR_INT(name, varname, opt, comment, check, update, default, minimum, maximum, blocksize)An
unsigned intsystem variable, which is typically a 4-byte unsigned word.MYSQL_THDVAR_UINT(name, opt, comment, check, update, default, min, max, blk)MYSQL_SYSVAR_UINT(name, varname, opt, comment, check, update, default, minimum, maximum, blocksize)A
longsystem variable, which is typically either a 4- or 8-byte signed word.MYSQL_THDVAR_LONG(name, opt, comment, check, update, default, min, max, blk)MYSQL_SYSVAR_LONG(name, varname, opt, comment, check, update, default, minimum, maximum, blocksize)An
unsigned longsystem variable, which is typically either a 4- or 8-byte unsigned word.MYSQL_THDVAR_ULONG(name, opt, comment, check, update, default, min, max, blk)MYSQL_SYSVAR_ULONG(name, varname, opt, comment, check, update, default, minimum, maximum, blocksize)A
long longsystem variable, which is typically an 8-byte signed word.MYSQL_THDVAR_LONGLONG(name, opt, comment, check, update, default, minimum, maximum, blocksize)MYSQL_SYSVAR_LONGLONG(name, varname, opt, comment, check, update, default, minimum, maximum, blocksize)An
unsigned long longsystem variable, which is typically an 8-byte unsigned word.MYSQL_THDVAR_ULONGLONG(name, opt, comment, check, update, default, minimum, maximum, blocksize)MYSQL_SYSVAR_ULONGLONG(name, varname, opt, comment, check, update, default, minimum, maximum, blocksize)A
doublesystem variable, which is typically an 8-byte signed word.MYSQL_THDVAR_DOUBLE(name, opt, comment, check, update, default, minimum, maximum, blocksize)MYSQL_SYSVAR_DOUBLE(name, varname, opt, comment, check, update, default, minimum, maximum, blocksize)An
unsigned longsystem variable, which is typically either a 4- or 8-byte unsigned word. The range of possible values is an ordinal of the number of elements in thetypelib, starting from 0.MYSQL_THDVAR_ENUM(name, opt, comment, check, update, default, typelib)MYSQL_SYSVAR_ENUM(name, varname, opt, comment, check, update, default, typelib)An
unsigned long longsystem variable, which is typically an 8-byte unsigned word. Each bit represents an element in thetypelib.MYSQL_THDVAR_SET(name, opt, comment, check, update, default, typelib)MYSQL_SYSVAR_SET(name, varname, opt, comment, check, update, default, typelib)
Internally, all mutable and plugin system variables are stored in aHASH structure.
Display of the server command-line help text is handled by compiling aDYNAMIC_ARRAY of all variables relevant to command-line options, sorting them, and then iterating through them to display each option.
When a command-line option has been handled, it is then removed from theargv by thehandle_option() function (my_getopt.c); in effect, it is consumed.
The server processes command-line options during the plugin installation process, immediately after the plugin has been successfully loaded but before the plugin initialization function has been called
Plugins loaded at runtime do not benefit from any configuration options and must have usable defaults. Once they are installed, they are loaded atmysqld initialization time and configuration options can be set at the command line or withinmy.cnf.
Plugins should consider thethd parameter to be read only.