4.4.2.2 Server Plugin Status and System Variables

The server plugin interface enables plugins to expose status and system variables using the status_vars and system_vars members of the general plugin descriptor.

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;
};

The following table shows the permissible status variable type 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 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. The following table shows the permissible flags.

  Table 4.2 Server Plugin System Variable Flags

  Flag Value	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 through 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(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 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)

  • A double system 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 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 structure.

Display of the server command-line help text is handled by compiling a DYNAMIC_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 the argv by the handle_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 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.