MySQL Internals Support for Plug-Ins

1 Plugins

[edit] Plugins

Beginning with MySQL 5.1, the server supports a plugin architecture for loading plugins. For example, several storage engines have been converted to plugins, and they can be selected or disabled at configuration time by means of command-line options to configure.

[edit] Command-Line Plugin Options

This section describes the command-line options that are used to control which plugins get built, and the autotools macros that enable plugin configuration support to be described.

Several configure options apply to plugin selection and building. You can build a plugin as static (compiled into the server) or dynamic (built as a dynamic library that must be installed using the INSTALL PLUGIN statement before it can be used). Some plugins might not support static or dynamic build.

configure --help shows the following information pertaining to plugins:

The plugin-related options
The names of all available plugins
For each plugin, a description of its purpose, which build types it supports (static or dynamic), and which plugin groups it is a part of.

The following configure options are used to select or disable plugins:

--with-plugins=PLUGIN[,PLUGIN]...
--with-plugins=GROUP
--with-plugin-PLUGIN
--without-plugin-PLUGIN

PLUGIN is an individual plugin name such as csv or archive.

As shorthand, GROUP is a configuration group name such as none (select no plugins), all (select all plugins), or max (select all plugins used in a mysqld-max server).

--with-plugins can take a list of one or more plugin names separated by commas, or a plugin group name. The named plugins are configured to be built as static plugins.

--with-plugin-PLUGIN configures the given plugin to be built as a static plugin.

--without-plugin-PLUGIN disables the given plugin from being built.

If a plugin is named both with a --with and --without option, the result is undefined.

For any plugin that is not explicitly or implicitly (as a member of a selected group) selected or disabled, it is selected to be built dynamically if it supports dynamic build, and is disabled if it does not support dynamic build. If no plugin options are given, default group is selected.

[edit] Autotools Plugin Macros

The following macros enable plugin support in the autotools configuration files.

Declaring a plugin:

MYSQL_PLUGIN(name, long-name, description [,configlist])

Each plugin is required to have MYSQL_PLUGIN() declared first. configlist is an optional argument that is a comma-separated list of configurations of which the module is a member. Example:

MYSQL_PLUGIN(ftexample, [Simple Parser], [Simple full-text parser plugin])

Declaring a storage engine plugin:

MYSQL_STORAGE_ENGINE(name, legacy-opt, long-name, description [,configlist])

This is a simple utility macro that calls MYSQL_PLUGIN. It performs the bare basics required to declare a storage engine plugin and provides support for handling the legacy configure command-line options. If legacy-opt is not specified, it will default to --with-name-storage-engine. Set the legacy-opt value to no if you do not want to handle any legacy option. This macro is roughly equivalent to:

MYSQL_PLUGIN(name, 'long-name, description)
MYSQL_PLUGIN_DEFINE(name, WITH_NAME_STORAGE_ENGINE)

Example:

MYSQL_STORAGE_ENGINE(berkeley,  berkeley-db, [BerkeleyDB Storage Engine],
      [Transactional Tables using BerkeleyDB], [max,max-no-ndb])

Declaring a C preprocessor variable:

MYSQL_PLUGIN_DEFINE(name, define-name)

When a plugin will be included in a static build, this will set a preprocessor variable to 1. These preprocessor variables are defined in config.h. Example:

MYSQL_PLUGIN_DEFINE(innobase, WITH_INNOBASE_STORAGE_ENGINE)

Declaring a source directory for a plugin:

MYSQL_PLUGIN_DIRECTORY(name, dir-name)

Includes the specified directory into the build. If a file named configure is detected in the directory, it will be executed as part of the configure build otherwise it is assumed that there is a Makefile to be built in that directory. Currently, there is only support for plugin directories to be specified in the storage/ and plugin/ subdirectories. Example:

MYSQL_PLUGIN_DIRECTORY(archive, [storage/archive])

Declaring a static library name for a plugin:

MYSQL_PLUGIN_STATIC(name, dir-name)

Sets the configure substitution @plugin_name_static_target@ to the supplied library name if the plugin is a static build. It also adds the library to the list of libraries to be linked into mysqld. It may either be just the name of the library (where, if there is a directory specified, the directory will be prepended for the link) or another make variable or substitution (in which case, it will be passed through as is). Example:

MYSQL_PLUGIN_STATIC(archive, [libarchive.a])
 MYSQL_PLUGIN_STATIC(berkeley, [[\$(bdb_libs_with_path)]])

Declaring a dynamic library name for a plugin:

MYSQL_PLUGIN_DYNAMIC(name, dso-name)

Sets the configure substitution @plugin_name_shared_target@ to the supplied dynamic shared object library name if the module is a dynamic build. Example:

MYSQL_PLUGIN_DYNAMIC(archive, [ha_archive.la])

Declaring a plugin as a mandatory module:

MYSQL_PLUGIN_MANDATORY(name)

Mandatory plugins cannot be disabled. Example:

MYSQL_PLUGIN_MANDATORY(myisam)

Declaring a plugin as disabled:

MYSQL_PLUGIN_DISABLED(name)

A disabled plugin will not be included in any build. If the plugin has been marked as MANDATORY, it will result in an autoconf error.

Declaring additional plugin configure actions:

MYSQL_PLUGIN_ACTIONS(name, configure-actions)

This is useful if there are additional configure actions required for a plugin. The configure-actions argument may either be the name of an autoconf macro or more autoconf script. Example:

MYSQL_PLUGIN_ACTIONS(ndbcluster,[MYSQL_SETUP_NDBCLUSTER])

Declaring plugin dependencies:

MYSQL_PLUGIN_DEPENDS(name, dependencies)

Declares all plugins, in a comma-separated list, that are required for the named plugin to be built. If the named plugin is selected, it will in turn enable all its dependencies. All plugins listed as a dependency must already have been declared with MYSQL_PLUGIN(). Example:

MYSQL_PLUGIN_DEPENDS(ndbcluster, [partition])

Performing the magic:

MYSQL_CONFIGURE_PLUGINS(default-names)

Actually performs the task of generating the shell scripts for configure based upon the declarations made previously. It emits the shell code necessary to check the options and sets the variables accordingly. Example:

MYSQL_CONFIGURE_PLUGINS([none])

Plugin-related configure errors:

When any plugin macro is called before MYSQL_PLUGIN() is declared for that plugin, configure aborts with an error.
When any of the plugins specified in the dependency list don't exist, configure aborts with an error.
When a mandatory plugin is specified in --without-plugin-PLUGIN, configure aborts with an error.
When a disabled plugin is specified in --with-modules=... or --with-plugin=PLUGIN, configure reports an error.
When an optional plugin that may only be built dynamically is specified in --with-plugins=... or --with-plugin-PLUGIN, configure emits a warning and continues to configure the plugin for dynamic build.
When an optional plugin that may only be built statically is specified neither in --with-plugins=... nor --without-plugin-PLUGIN, configure emits a warning but should proceed anyway.

Avoiding configure.in changes:

If a plugin source (which is located in a subdirectory of the storage/ or plugin/ directory) contains a plug.in file (for example, storage/example/plug.in), this file will be included as a part of configure.in. This way, configure.in does not need to be modified to add a new plugin to the build.
A plug.in file may contain everything, particularly all MYSQL_PLUGIN_xxx macros as just described. The plug.in file does not need to specify MYSQL_PLUGIN_DIRECTORY; it is set automatically to the directory of the plug.in file.

[edit] Specifying mysqld Variables within a Plugin

The basic header for a server variable structure is as follows:

struct st_mysql_sys_var {

 int flags;
 const char *name, *comment;
 int (*check)(THD*, struct st_mysql_sys_var *, void*, Item*);
 void (*update)(THD*, struct st_mysql_sys_var *, void*, void*);

};

Additional fields are append as required depending upon the flags.

Typical plugin implementors do not need to worry about these internal structurs and are able to declare their server variables by use of the conveience macros.

During the following definitions...

 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
 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, minimum, maximum, blocksize - default/limits for variable

Typical flags:

 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 cmd line.

 PLUGIN_VAR_NOCMDARG
   Indicates that no argument is required at the command line.
   (typically used for BOOL 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 STR variables. Indicates that memory is to be alloced for
   storage of the string.

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.

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,

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;

 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 NUL 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 are accessible at the command line and my.cnf

[edit] Additional Accessors for plugins

Starting with MySQL 5.1.21 the following additional accessors are made available to all plug-ins:

Full definition of MYSQL_LEX_STRING (identical to LEX_STRING from m_string.h)
Full definition of MYSQL_XID (binary compatible with XID from handler.h)
mysql_tmpfile(), creates a temporary file in mysqld's tmpdir
thd_killed(), to check killed state of connection
thd_alloc() and similar allocation functions
thd_get_xid(), to get XID of connection's transaction
mysql_query_cache_invalidate4(), to invalidate a table's query cache entries

Retrieved from "http://forge.mysql.com/wiki/MySQL_Internals_Support_for_Plug-Ins"

This page has been accessed 4,212 times. This page was last modified 20:28, 5 June 2008.

MySQL Forge

Resources for the MySQL Community

MySQL Internals Support for Plug-Ins

Contents

[edit] Plugins

[edit] Command-Line Plugin Options

[edit] Autotools Plugin Macros

[edit] Specifying mysqld Variables within a Plugin

[edit] Additional Accessors for plugins

Find

Browse

Edit

This page

Context

My pages

Special pages