client_plugin.cc File Reference

Support code for the client side (libmysql) plugins. More...

#include "my_config.h"
#include <mysql/client_plugin.h>
#include <stdarg.h>
#include <stdlib.h>
#include <sys/types.h>
#include "errmsg.h"
#include "my_alloc.h"
#include "my_dbug.h"
#include "my_inttypes.h"
#include "my_io.h"
#include "my_macros.h"
#include "my_psi_config.h"
#include "my_sys.h"
#include "my_thread.h"
#include "mysql.h"
#include "mysql/psi/mysql_memory.h"
#include "mysql/psi/mysql_mutex.h"
#include "mysql/service_mysql_alloc.h"
#include "mysql/strings/m_ctype.h"
#include "nulls.h"
#include "sql_common.h"
#include "strxnmov.h"
#include "template_utils.h"
#include <dlfcn.h>
#include <mysql/plugin_client_telemetry.h>

Classes
struct	st_client_plugin_int

Functions
static void	init_client_plugin_psi_keys ()
static int	is_not_initialized (MYSQL *mysql, const char *name)
static struct st_mysql_client_plugin *	find_plugin (const char *name, int type)
	finds a plugin in the list More...
static struct st_mysql_client_plugin *	do_add_plugin (MYSQL *mysql, struct st_mysql_client_plugin *plugin, void *dlhandle, int argc, va_list args)
	verifies the plugin and adds it to the list More...
static struct st_mysql_client_plugin *	add_plugin_noargs (MYSQL *mysql, struct st_mysql_client_plugin *plugin, void *dlhandle, int argc,...)
static struct st_mysql_client_plugin *	add_plugin_withargs (MYSQL *mysql, struct st_mysql_client_plugin *plugin, void *dlhandle, int argc, va_list args)
static void	load_env_plugins (MYSQL *mysql)
	Loads plugins which are specified in the environment variable LIBMYSQL_PLUGINS. More...
int	mysql_client_plugin_init ()
	Initializes the client plugin layer. More...
void	mysql_client_plugin_deinit ()
	Deinitializes the client plugin layer. More...
struct st_mysql_client_plugin *	mysql_client_register_plugin (MYSQL *mysql, struct st_mysql_client_plugin *plugin)
	adds a plugin structure to the list of loaded plugins More...
struct st_mysql_client_plugin *	mysql_load_plugin_v (MYSQL *mysql, const char *name, int type, int argc, va_list args)
	loads a plugin and initializes it, taking va_list as an argument More...
struct st_mysql_client_plugin *	mysql_load_plugin (MYSQL *mysql, const char *name, int type, int argc,...)
	loads a plugin and initializes it More...
struct st_mysql_client_plugin *	mysql_client_find_plugin (MYSQL *mysql, const char *name, int type)
	finds an already loaded plugin by name, or loads it, if necessary More...
int	mysql_plugin_options (struct st_mysql_client_plugin *plugin, const char *option, const void *value)
	set plugin options More...
int	mysql_plugin_get_option (struct st_mysql_client_plugin *plugin, const char *option, void *value)
	get plugin options More...

Variables
struct st_mysql_client_plugin_TELEMETRY *	client_telemetry_plugin
	The global telemetry_plugin pointer. More...
PSI_memory_key	key_memory_root
PSI_memory_key	key_memory_load_env_plugins
PSI_mutex_key	key_mutex_LOCK_load_client_plugin
static PSI_mutex_info	all_client_plugin_mutexes []
static PSI_memory_info	all_client_plugin_memory []
static bool	initialized = false
static MEM_ROOT	mem_root
static const char *	plugin_declarations_sym
static uint	plugin_version [MYSQL_CLIENT_MAX_PLUGINS]
struct st_client_plugin_int *	plugin_list [MYSQL_CLIENT_MAX_PLUGINS]
static mysql_mutex_t	LOCK_load_client_plugin

Detailed Description

Support code for the client side (libmysql) plugins.

Client plugins are somewhat different from server plugins, they are simpler.

They do not need to be installed or in any way explicitly loaded on the client, they are loaded automatically on demand. One client plugin per shared object, soname must match the plugin name.

There is no reference counting and no unloading either.

Function Documentation

add_plugin_noargs()

static struct st_mysql_client_plugin * add_plugin_noargs ( MYSQL *  mysql, struct st_mysql_client_plugin *  plugin, void *  dlhandle, int  argc,   ...  )

static

add_plugin_withargs()

static struct st_mysql_client_plugin * add_plugin_withargs ( MYSQL *  mysql, struct st_mysql_client_plugin *  plugin, void *  dlhandle, int  argc, va_list  args  )

static

do_add_plugin()

static struct st_mysql_client_plugin * do_add_plugin ( MYSQL *  mysql, struct st_mysql_client_plugin *  plugin, void *  dlhandle, int  argc, va_list  args  )

static

verifies the plugin and adds it to the list

Parameters

mysql	MYSQL structure (for error reporting)
plugin	plugin to install
dlhandle	a handle to the shared object (returned by dlopen) or 0 if the plugin was not dynamically loaded
argc	number of arguments in the 'va_list args'
args	arguments passed to the plugin initialization function

Return values

a	pointer to an installed plugin or 0

find_plugin()

static struct st_mysql_client_plugin * find_plugin ( const char *  name, int  type  )

static

finds a plugin in the list

Parameters

name	plugin name to search for
type	plugin type

Note

this does NOT necessarily need a mutex, take care!

Return values

a	pointer to a found plugin or 0

init_client_plugin_psi_keys()

static void init_client_plugin_psi_keys ( )

static

is_not_initialized()

static int is_not_initialized ( MYSQL *  mysql, const char *  name  )

static

load_env_plugins()

static void load_env_plugins ( MYSQL *  mysql )

static

Loads plugins which are specified in the environment variable LIBMYSQL_PLUGINS.

Multiple plugins must be separated by semicolon. This function doesn't return or log an error.

The function is be called by mysql_client_plugin_init

mysql_client_find_plugin()

struct st_mysql_client_plugin * mysql_client_find_plugin	(	struct MYSQL *	mysql,
		const char *	name,
		int	type
	)

finds an already loaded plugin by name, or loads it, if necessary

Parameters

mysql	MYSQL structure.
name	a name of the plugin to load
type	type of plugin that should be loaded

Return values

a	pointer to the plugin, or NULL in case of a failure

mysql_client_plugin_deinit()

void mysql_client_plugin_deinit

(

)

Deinitializes the client plugin layer.

Unloades all client plugins and frees any associated resources.

mysql_client_plugin_init()

int mysql_client_plugin_init

(

)

Initializes the client plugin layer.

This function must be called before any other client plugin function.

Return values

0	successful
!=	0 error occurred

mysql_client_register_plugin()

struct st_mysql_client_plugin * mysql_client_register_plugin	(	struct MYSQL *	mysql,
		struct st_mysql_client_plugin *	plugin
	)

adds a plugin structure to the list of loaded plugins

This is useful if an application has the necessary functionality (for example, a special load data handler) statically linked into the application binary. It can use this function to register the plugin directly, avoiding the need to factor it out into a shared object.

Parameters

mysql	MYSQL structure. It is only used for error reporting
plugin	an st_mysql_client_plugin structure to register

Return values

a	pointer to the plugin, or NULL in case of a failure

mysql_load_plugin()

struct st_mysql_client_plugin * mysql_load_plugin	(	struct MYSQL *	mysql,
		const char *	name,
		int	type,
		int	argc,
			...
	)

loads a plugin and initializes it

Parameters

mysql	MYSQL structure.
name	a name of the plugin to load
type	type of plugin that should be loaded, -1 to disable type check
argc	number of arguments to pass to the plugin initialization function
...	arguments for the plugin initialization function

Return values

a	pointer to the loaded plugin, or NULL in case of a failure

mysql_load_plugin_v()

struct st_mysql_client_plugin * mysql_load_plugin_v	(	struct MYSQL *	mysql,
		const char *	name,
		int	type,
		int	argc,
		va_list	args
	)

loads a plugin and initializes it, taking va_list as an argument

This is the same as mysql_load_plugin, but take va_list instead of a list of arguments.

Parameters

mysql	MYSQL structure.
name	a name of the plugin to load
type	type of plugin that should be loaded, -1 to disable type check
argc	number of arguments to pass to the plugin initialization function
args	arguments for the plugin initialization function

Return values

a	pointer to the loaded plugin, or NULL in case of a failure

mysql_plugin_get_option()

int mysql_plugin_get_option	(	struct st_mysql_client_plugin *	plugin,
		const char *	option,
		void *	value
	)

get plugin options

Can be used to get options from a plugin. This function may be called multiple times to get several options

Parameters

	plugin	an st_mysql_client_plugin structure
	option	a string which specifies the option to get
[out]	value	value for the option.

Return values

0	on success, 1 in case of failure

mysql_plugin_options()

int mysql_plugin_options	(	struct st_mysql_client_plugin *	plugin,
		const char *	option,
		const void *	value
	)

set plugin options

Can be used to set extra options and affect behavior for a plugin. This function may be called multiple times to set several options

Parameters

plugin	an st_mysql_client_plugin structure
option	a string which specifies the option to set
value	value for the option.

Return values

0	on success, 1 in case of failure

Variable Documentation

all_client_plugin_memory

PSI_memory_info all_client_plugin_memory[]

static

Initial value:

= {
    {&key_memory_root, "root", PSI_FLAG_ONLY_GLOBAL_STAT, 0, PSI_DOCUMENT_ME},
    {&key_memory_load_env_plugins, "load_env_plugins",
     PSI_FLAG_ONLY_GLOBAL_STAT, 0, PSI_DOCUMENT_ME}}

all_client_plugin_mutexes

PSI_mutex_info all_client_plugin_mutexes[]

static

Initial value:

= {
    {&key_mutex_LOCK_load_client_plugin, "LOCK_load_client_plugin",
     PSI_FLAG_SINGLETON, 0, PSI_DOCUMENT_ME}}

client_telemetry_plugin

struct st_mysql_client_plugin_TELEMETRY* client_telemetry_plugin

The global telemetry_plugin pointer.

initialized

bool initialized = false

static

key_memory_load_env_plugins

PSI_memory_key key_memory_load_env_plugins

key_memory_root

PSI_memory_key key_memory_root

key_mutex_LOCK_load_client_plugin

PSI_mutex_key key_mutex_LOCK_load_client_plugin

LOCK_load_client_plugin

mysql_mutex_t LOCK_load_client_plugin

static

mem_root

MEM_ROOT mem_root

static

plugin_declarations_sym

const char* plugin_declarations_sym

static

Initial value:

=
    "_mysql_client_plugin_declaration_"

plugin_list

struct st_client_plugin_int* plugin_list[MYSQL_CLIENT_MAX_PLUGINS]

plugin_version

uint plugin_version[MYSQL_CLIENT_MAX_PLUGINS]

static

Initial value:

= {
    0, 
    0, 
    MYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION,
    MYSQL_CLIENT_TRACE_PLUGIN_INTERFACE_VERSION,
    MYSQL_CLIENT_TELEMETRY_PLUGIN_INTERFACE_VERSION,
}