MySQL server 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 also available to user-defined functions (UDFs).
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.
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.
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, which is the
“umbrella” header that includes all available
service-specific header files.
Service-specific headers have names of the form
service_.
xxx.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.
Current services include the following, and others can be implemented:
my_snprintf: A string-formatting service
that produces consistent results across platforms.
my_thd_scheduler: A service for plugins to
select a thread scheduler.
thd_alloc: A memory-allocation service.
thd_wait: A service for plugins to report
when they are going to sleep or stall.
For developers who wish to modify the server to add a new service, see MySQL Internals: MySQL Services for Plugins.
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 the
my_snprintf service. Within a MySQL source
distribution, that plugin is located in the
plugin/daemon_example directory.
To use a service or services from within a plugin, the plugin
source file must include the plugin.h header
file to access service-related information:
#include <mysql/plugin.h>
This does not represent any additional setup cost. 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, use the
-lmysqlservices flag at link time to link in
the libmysqlservices library. For example, for
CMake, put this in the top-level
CMakeLists.txt file:
FIND_LIBRARY(MYSQLSERVICES_LIB mysqlservices
PATHS "${MYSQL_SRCDIR}/libservices" NO_DEFAULT_PATH)
Put this in the CMakeLists.txt file in the
directory containing the plugin source:
# the plugin needs the mysql services library for error logging
TARGET_LINK_LIBRARIES (your_plugin_library_name ${MYSQLSERVICES_LIB})