The plugin interface enables plugins to expose status and system variables.
The status_vars
member of the general
plugin descriptor, if not 0, points to an array of
st_mysql_show_var
structures, each of which
describes one status variable, followed by a structure with
all members set to 0. The st_mysql_show_var
structure has this definition:
struct st_mysql_show_var { const char *name; char *value; enum enum_mysql_show_type type; };
When the plugin is installed, the plugin name and the
name
value are joined with an underscore to
form the name displayed by SHOW
STATUS
.
The following table shows the allowable status variable
type
values and what the corresponding
variable should be.
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 another st_mysql_show_var array |
SHOW_FUNC |
Pointer to a function |
SHOW_DOUBLE |
Pointer to a double |
For the SHOW_FUNC
type, the function is
called and fills in its out
parameter,
which then provides information about the variable to be
displayed. The function has this signature:
#define SHOW_VAR_FUNC_BUFF_SIZE 1024 typedef int (*mysql_show_var_func) (void *thd, struct st_mysql_show_var *out, char *buf);
The system_vars
member, if not 0, points to
an array of st_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. The
st_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 the
name
field.
opt
: Additional use flags for the
system variable. Supported flags are shown in the
following table.
Flag | Description |
---|---|
PLUGIN_VAR_READONLY |
The system variable is read only |
PLUGIN_VAR_NOSYSVAR |
The system variable is not user visible at runtime |
PLUGIN_VAR_NOCMDOPT |
The system variable is not configurable from the command line |
PLUGIN_VAR_NOCMDARG |
No argument is required at the command line (typically used for boolean variables) |
PLUGIN_VAR_RQCMDARG |
An argument is required at the command line (this is the default) |
PLUGIN_VAR_OPCMDARG |
An argument is optional at the command line |
PLUGIN_VAR_MEMALLOC |
Used 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.
NULL
if this variable is to be hidden.
check
: The check function,
NULL
for default.
update
: The update function,
NULL
for 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 of blocksize
.
A system variable may be accessed either by using the static
variable directly or by using the
SYSVAR()
accessor macro. The
SYSVAR()
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 via the
THDVAR()
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 to
mysqld before use. This is done by
constructing a NULL
-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(my_foo), MYSQL_SYSVAR(some_flag), NULL }; mysql_declare_plugin(fooplug) { MYSQL_..._PLUGIN, &plugin_data, "fooplug", "This does foo!", PLUGIN_LICENSE_GPL, foo_init, foo_fini, 0x0001, NULL, my_plugin_vars, NULL } mysql_declare_plugin_end;
The following convenience macros enable you to declare different types of system variables:
Boolean system variables of type
my_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 int
system 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 int
system 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 long
system 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 long
system 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 long
system 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 long
system
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)
An unsigned long
system 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 the
typelib
, 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 long
system
variable, which is typically an 8-byte unsigned word.
Each bit represents an element in the
typelib
.
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 a HASH
.
Display of the server command-line help text is handled by
compiling a DYNAMIC_ARRAY
of all variables
relevent 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 the argv
by the
handle_option()
function
(my_getopt.c
); in effect, it is consumed.
The processing of command-line options is performed 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 usuable defaults. Once
they are installed, they are loaded at
mysqld initialization time and
configuration options can be set at the command line or within
my.cnf
.
Plugins should consider the thd
parameter
to be read only.
User Comments
Add your own comment.