Skip navigation links
22.3 Adding New Functions to MySQL »
Section Navigation      [Toggle]

22.2.6. MySQL Services for Plugins

As of MySQL 5.5, plugins have access to server “services.” The services interface exposes server functionality that plugins can call. It complements the plugin API and has these characteristics:

  • Services enable plugins to access code inside the server using ordinary function calls.

  • Services are portable and work on multiple platforms.

  • The interface includes a versioning mechanism so that service versions supported by the server can be checked at load time against plugin versions. Versioning protects against incompatibilities between the version of a service that the server provides and the version of the service expected or required by a plugin.

Current services include my_snprintf and thd_alloc, and others can be implemented:

  • my_snprintf provides a string-formatting service that produces consistent results across platforms.

  • thd_alloc provides a memory-allocation service.

The plugin services interface differs from the plugin API as follows:

  • The plugin API enables plugins to be used by the server. The calling initiative lies with the server to invoke plugins. This enables plugins to extend server functionality or register to receive notifications about server processing.

  • The plugin services interface enables plugins to call code inside the server. The calling initiative lies with plugins to invoke service functions. This enables functionality already implemented in the server to be used by many plugins; they need not individually implement it themselves.

For developers who wish to modify the server to add a new service, see MySQL Services for Plugins in the MySQL Internals Manual.

The remainder of this section describes how a plugin uses server functionality that is available as a service. See also the source for the “daemon” example plugin, which uses this service. Within a MySQL source distribution, that plugin is located in the plugin/daemon_example directory.

To determine what services exist and what functions they provide, look in the include/mysql directory of a MySQL source distribution. The relevant files are:

  • plugin.h includes services.h.

  • services.h is the “umbrella” header that includes all available service-specific header files.

  • Service-specific headers have names like service_my_snprintf.h or service_thd_alloc.h.

Each service-specific header should contain comments that provide full usage documentation for a given service, including what service functions are available, their calling sequences, and return values.

After you decide which service or services you want to use from within a plugin, there is really no setup involved, other than to include the plugin.h header file to access service-related information: 

#include <mysql/plugin.h>

But a plugin must include that file anyway because it contains definitions and structures that every plugin needs.

To access a service, a plugin calls service functions like any other function. For example, to format a string into a buffer for printing, call the my_snprintf() function provided by the service of the same name: 

char buffer[BUFFER_SIZE];

my_snprintf(buffer, sizeof(buffer), format_string, argument_to_format, ...);

When you build your plugin, you must link in the libmysqlservices library. Use the -lmysqlservices flag at link time. For example, the Makefile.am file for a plugin might look like this: 

pkgplugindir=$(pkglibdir)/plugin
INCLUDES= -I$(top_builddir)/include -I$(top_srcdir)/include
pkgplugin_LTLIBRARIES= mypluglib.la
mypluglib_la_SOURCES= plugin_example.c
mypluglib_la_LDFLAGS= -module -rpath $(pkgplugindir) \
        -L$(libdir)/mysql -lmysqlservices
mypluglib_la_CFLAGS= -DMYSQL_DYNAMIC_PLUGIN