Skip navigation links
22.2.3.2 Type-Specific Plugin Structures and Functions »
Section Navigation      [Toggle]

22.2.3.1. General Plugin Structures and Functions

Every plugin must have a general plugin declaration. The declaration corresponds to the st_mysql_plugin structure in the plugin.h file: 

struct st_mysql_plugin
{
  int type;             /* the plugin type (a MYSQL_XXX_PLUGIN value)   */
  void *info;           /* pointer to type-specific plugin descriptor   */
  const char *name;     /* plugin name                                  */
  const char *author;   /* plugin author (for SHOW PLUGINS)             */
  const char *descr;    /* general descriptive text (for SHOW PLUGINS ) */
  int license;          /* the plugin license (PLUGIN_LICENSE_XXX)      */
  int (*init)(void *);  /* the function to invoke when plugin is loaded */
  int (*deinit)(void *);/* the function to invoke when plugin is unloaded */
  unsigned int version; /* plugin version (for SHOW PLUGINS)            */
  struct st_mysql_show_var *status_vars;
  struct st_mysql_sys_var **system_vars; 
  void * __reserved1;   /* placeholder for system variables             */
};

The st_mysql_plugin structure is common to every type of plugin. Its members should be filled in as follows:

  • type

    The plugin type. This must be one of the plugin-type values from plugin.h. For a full-text parser plugin, the type value is MYSQL_FTPARSER_PLUGIN.

  • info

    A pointer to the descriptor for the plugin. Unlike the general plugin declaration structure, this descriptor's structure depends on the particular type of plugin. Each descriptor has a version number that indicates the API version for that type of plugin, plus any other members needed. The descriptor for full-text plugins is described in Section 22.2.3.2, “Type-Specific Plugin Structures and Functions”.

  • name

    The plugin name. This is the name that will be listed in the plugin table and by which you refer to the plugin in SQL statements such as INSTALL PLUGIN and UNINSTALL PLUGIN.

  • author

    The plugin author. This can be whatever you like.

  • desc

    A general description of the plugin. This can be whatever you like.

  • license

    The plugin license type. The value can be one of PLUGIN_LICENSE_PROPRIETARY, PLUGIN_LICENSE_GPL, or PLUGIN_LICENSE_BSD.

  • init

    A once-only initialization function. This is executed when the plugin is loaded, which happens for INSTALL PLUGIN or, for plugins listed in the plugin table, at server startup. The function takes no arguments. It returns zero for success and nonzero for failure. If an init function is unneeded for a plugin, it can be specified as 0.

  • deinit

    A once-only deinitialization function. This is executed when the plugin is unloaded, which happens for UNINSTALL PLUGIN or, for plugins listed in the plugin table, at server shutdown. The function takes no arguments. It returns zero for success and nonzero for failure. If a deinit function is unneeded for a plugin, it can be specified as 0.

  • version

    The plugin version number. When the plugin is installed, this value can be retrieved from the INFORMATION_SCHEMA.PLUGINS table. The value includes major and minor numbers. If you write the value as a hex constant, the format is 0xMMNN, where MM and NN are the major and minor numbers, respectively. For example, 0x0302 represents version 3.2.

  • status_vars

    A pointer to a structure for status variables associated with the plugin, or 0 if there are no such variables. When the plugin is installed, these variables are displayed in the output of the SHOW STATUS statement.

  • __reserved1, __reserved2

    These are placeholders for the future. Currently, they should be set to NULL.

The init and deinit functions in the general plugin declaration are invoked only when loading and unloading the plugin. They have nothing to do with use of the plugin such as happens when an SQL statement causes the plugin to be invoked.

The status_vars member, 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

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 — is an unquoted identifier for the system variable.

  • varname — is the identifier for the static variable, where not available, it is the same as field name.

  • opt — additional use flags for the system variable. Supported flags are shown in the table below:

    Flag Description
    PLUGIN_VAR_READONLY Indicates that the system variable is READ ONLY.
    PLUGIN_VAR_NOSYSVAR Indicates that the system variable is not user visible at run time.
    PLUGIN_VAR_NOCMDOPT Indicates that the system variable is not configuable from the command line.
    PLUGIN_VAR_NOCMDARG Indicates that no argument is required at the command line. (typically used for boolean variables).
    PLUGIN_VAR_RQCMDARG Indicates that an argument is required at the command line (this is the default).
    PLUGIN_VAR_OPCMDARG Indicates that an argument is optional at the command line.
    PLUGIN_VAR_MEMALLOC Used for string variables. Indicates that memory is to be alloced for storage of the string.

  • comment — descriptive comment, appears in help text. NULL if this variable is to be hidden.

  • check — check function, NULL for default.

  • update — update function, NULL for default.

  • default — the default value.

  • minimum — the minimum value.

  • maximum — the maximum value.

  • blocksize — the blocksize. When a value is set, it will be rounded to the nearest blocksize.

System variables may be access by either using the static variable directly or by using the SYSVAR() accessor macro. Use of the SYSVAR() macro should only usually occur when the code cannot directly access the underlying variable and is provided for completeness.

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 only be accessed via the THDVAR() accessor macro. 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 variables must 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;

For convenience, you can use the following macros to define different types of system variable: 

  •  MYSQL_THDVAR_BOOL(name, opt, comment, check, update, default)
 MYSQL_SYSVAR_BOOL(name, varname, opt, comment, check, update, default)

    Used to declare a system variable of type my_bool, which is a 1 byte boolean. (0 == FALSE, 1 == TRUE) 

  •  MYSQL_THDVAR_STR(name, opt, comment, check, update, default)
MYSQL_SYSVAR_STR(name, varname, opt, comment, check, update, default)

    Used to declare a system variable of type char*, which is a pointer to a NULL terminated string. 

  • 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)

    Used to declare a system variable of type int, which is typically a 4 byte signed 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)

    Used to declare a system variable of type unsigned int, which is typically a 4 byte unsigned 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)

    Used to declare a system variable of type long, which is typically either a 4 or 8 byte signed 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)

    Used to declare a system variable of type unsigned long, which is typically either a 4 or 8 byte unsigned 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)

    Used to declare a system variable of type long long, which is typically an 8 byte signed 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)

    Used to declare a system variable of type unsigned long long, which is typically an 8 byte unsigned word. 

  • MYSQL_THDVAR_ENUM(name, opt, comment, check, update, default, typelib)
MYSQL_SYSVAR_ENUM(name, varname, opt, comment, check, update,
                default, typelib)

    Used to declare a system variable of type unsigned long, which is typically either 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_SET(name, opt, comment, check, update, default, typelib)
MYSQL_SYSVAR_SET(name, varname, opt, comment, check, update,
               default, typelib)

    Used to declare a system variable of type unsigned long long, which is typically an 8 byte unsigned word. Each bit represents an element in the typelib.

Internally, all mutable and plugin system variables are stored in a HASH.

Display of the server command line verbose help text is handled by compiling a DYNAMIC_ARRAY of all variables relevent to command line options, sorting them, and then enumerating through then 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 run time do not benefit from any configuration options and must have usuable defaults. Once they are installed, they are loaded at mysqld initialization time and so configuration options can be set at the command line and within my.cnf.

Plugins should consider the thd parameter to be read only.