From 7464dc2e4120aa7e66dc0027c5d214ac4118f479 Mon Sep 17 00:00:00 2001 From: "Georgi (Joro) Kodinov" Date: Wed, 19 Aug 2026 15:31:10 +0300 Subject: [PATCH] MDBF-1224: fix the structure of the plugin MD file This requires moxygen 2.1.16! Added a check Implemented a structure for the plugin API documentation. On the top there's a main page to give top level overview and concepts. It eventually references the Moxygen documentation. The moxygen documentation is a series of nested doxygen groups that define the structure for the whole Plugin API documentation. There are top levels like "server plugin API" and "client plugin API". These branch into futher subgroups as needed. Addressed githib copilot review comments. --- .../mysql/Doxyfile.generated_docs_plugin_api | 2 +- include/mysql/auth_dialog_client.h | 12 +- include/mysql/client_plugin.h | 11 +- include/mysql/generate_plugin_api_docs.sh | 37 ++- include/mysql/index.dox | 145 +++++++++- include/mysql/plugin.h | 257 +++++++++++++----- include/mysql/plugin_audit.h | 41 ++- include/mysql/plugin_auth.h | 27 +- include/mysql/plugin_auth_common.h | 16 +- include/mysql/plugin_data_type.h | 19 +- include/mysql/plugin_encryption.h | 34 ++- include/mysql/plugin_ftparser.h | 215 +++++++++------ include/mysql/plugin_function.h | 14 +- include/mysql/plugin_password_validation.h | 16 +- include/mysql/psi/mysql_file.h | 8 +- include/mysql/psi/mysql_idle.h | 10 +- include/mysql/psi/mysql_mdl.h | 13 +- include/mysql/psi/mysql_memory.h | 17 +- include/mysql/psi/mysql_ps.h | 9 + include/mysql/psi/mysql_socket.h | 22 +- include/mysql/psi/mysql_sp.h | 9 + include/mysql/psi/mysql_stage.h | 10 +- include/mysql/psi/mysql_statement.h | 12 +- include/mysql/psi/mysql_table.h | 10 +- include/mysql/psi/mysql_thread.h | 12 +- include/mysql/psi/mysql_transaction.h | 8 +- include/mysql/psi/psi.h | 8 +- include/mysql/psi/psi_abi_v0.h | 7 +- include/mysql/psi/psi_abi_v1.h | 7 +- include/mysql/psi/psi_abi_v2.h | 7 + include/mysql/psi/psi_base.h | 6 +- include/mysql/psi/psi_memory.h | 2 +- include/mysql/service_base64.h | 16 +- include/mysql/service_debug_sync.h | 40 +-- include/mysql/service_encryption.h | 16 +- include/mysql/service_encryption_scheme.h | 10 +- include/mysql/service_json.h | 28 +- include/mysql/service_kill_statement.h | 32 ++- include/mysql/service_log_warnings.h | 21 +- include/mysql/service_logger.h | 24 +- include/mysql/service_md5.h | 13 +- include/mysql/service_my_crypt.h | 14 +- include/mysql/service_my_print_error.h | 10 +- include/mysql/service_my_snprintf.h | 101 ++++--- include/mysql/service_print_check_msg.h | 17 +- include/mysql/service_progress_report.h | 18 +- include/mysql/service_sha1.h | 24 +- include/mysql/service_sha2.h | 56 ++-- include/mysql/service_sql.h | 78 +++--- include/mysql/service_thd.h | 26 +- include/mysql/service_thd_alloc.h | 66 ++--- include/mysql/service_thd_autoinc.h | 26 +- include/mysql/service_thd_error_context.h | 55 ++-- include/mysql/service_thd_mdl.h | 18 +- include/mysql/service_thd_rnd.h | 28 +- include/mysql/service_thd_specifics.h | 70 +++-- include/mysql/service_thd_timezone.h | 24 +- include/mysql/service_thd_wait.h | 78 +++--- include/mysql/service_wsrep.h | 150 +++++----- include/mysql/services.h | 13 +- 60 files changed, 1424 insertions(+), 671 deletions(-) diff --git a/include/mysql/Doxyfile.generated_docs_plugin_api b/include/mysql/Doxyfile.generated_docs_plugin_api index 1da1a90ce8ffd..4e00feaa9c810 100644 --- a/include/mysql/Doxyfile.generated_docs_plugin_api +++ b/include/mysql/Doxyfile.generated_docs_plugin_api @@ -9,4 +9,4 @@ RECURSIVE = YES GENERATE_HTML = NO GENERATE_LATEX = NO GENERATE_XML = YES -PREDEFINED = HAVE_PSI_SOCKET_INTERFACE HAVE_PSI_1 USE_PSI_1 +PREDEFINED = HAVE_PSI_SOCKET_INTERFACE HAVE_PSI_1 USE_PSI_1 MYSQL_DYNAMIC_PLUGIN __cplusplus diff --git a/include/mysql/auth_dialog_client.h b/include/mysql/auth_dialog_client.h index f1ad3e6983da9..4e42f9b3aa42e 100644 --- a/include/mysql/auth_dialog_client.h +++ b/include/mysql/auth_dialog_client.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_AUTH_DIALOG_CLIENT_INCLUDED /* Copyright (C) 2010 Sergei Golubchik and Monty Program Ab This program is free software; you can redistribute it and/or modify @@ -14,15 +13,22 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_AUTH_DIALOG_CLIENT_INCLUDED +#define MYSQL_AUTH_DIALOG_CLIENT_INCLUDED + /** @file Definitions needed to use Dialog client authentication plugin */ +/** + @addtogroup plugin_client_api + @{ + */ + struct st_mysql; -#define MYSQL_AUTH_DIALOG_CLIENT_INCLUDED /** type of the mysql_authentication_dialog_ask function @@ -53,4 +59,6 @@ typedef char *(*mysql_authentication_dialog_ask_t)(struct st_mysql *mysql, #define PASSWORD_QUESTION "\4" #define LAST_PASSWORD "\5" +/** @} */ + #endif diff --git a/include/mysql/client_plugin.h b/include/mysql/client_plugin.h index 404c3f1eafc10..c9b58c2303261 100644 --- a/include/mysql/client_plugin.h +++ b/include/mysql/client_plugin.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_CLIENT_PLUGIN_INCLUDED /* Copyright (C) 2010 Sergei Golubchik and Monty Program Ab Copyright (c) 2010, 2011, Oracle and/or its affiliates. @@ -15,6 +14,8 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_CLIENT_PLUGIN_INCLUDED +#define MYSQL_CLIENT_PLUGIN_INCLUDED /** @file @@ -22,8 +23,12 @@ This file defines the API for plugins that work on the client side */ -#define MYSQL_CLIENT_PLUGIN_INCLUDED +/** + @defgroup plugin_client_api Client Plugin API + API for plugins that work on the client side + @{ +*/ /* On Windows, exports from DLL need to be declared Also, plugin needs to be declared as extern "C" because MSVC @@ -185,5 +190,7 @@ mysql_client_register_plugin(struct st_mysql *mysql, **/ int mysql_plugin_options(struct st_mysql_client_plugin *plugin, const char *option, const void *value); + +/** @} */ #endif diff --git a/include/mysql/generate_plugin_api_docs.sh b/include/mysql/generate_plugin_api_docs.sh index 5e4be538bb3fa..46a782b092abc 100644 --- a/include/mysql/generate_plugin_api_docs.sh +++ b/include/mysql/generate_plugin_api_docs.sh @@ -10,7 +10,33 @@ # md/.md - documentation for group # md/.md - documentation for each # Note: target_dir is created if not present. -# Note: requires at least moxygen 2.1.11 + +# compare version numbers +# usage: vercmp +# with format for versions xxx.xxx.xxx +# returns: 0 if versionnr1 equal or greater +# 1 if versionnr1 lower + +vercmp() +{ + local a1 b1 c1 a2 b2 c2 + v1=$1 + v2=$2 + set -- $( echo "$v1" | sed 's/\./ /g' ) + a1=$1 b1=$2 c1=$3 + set -- $( echo "$v2" | sed 's/\./ /g' ) + a2=$1 b2=$2 c2=$3 + ret=$(( (a1-a2)*1000000+(b1-b2)*1000+c1-c2 )) + if [ $ret -lt 0 ] ; then + v=-1 + elif [ $ret -eq 0 ] ; then + v=0 + else + v=1 + fi + printf "%d" $v + return +} # If no target_dir is specified, the current directory is used. if [ -n "$1" ]; then @@ -22,6 +48,15 @@ fi # Exit on error, undefined variable, or pipe failure set -euo pipefail +#check if moxygen version is good enough +moxygen_version=$(moxygen --version) +require_moxygen_version="2.1.16" +if [ $(vercmp "$moxygen_version" "$require_moxygen_version") -lt 0 ]; then + echo "moxygen version $require_moxygen_version or higher is required," \ + "but $moxygen_version is installed." + exit 1 +fi + # Clean up the output directory, if it exists rm -rf "$TARGET_DIR/md" rm -rf "$TARGET_DIR/xml" diff --git a/include/mysql/index.dox b/include/mysql/index.dox index 57fb676716ae7..adbe07d14caa7 100644 --- a/include/mysql/index.dox +++ b/include/mysql/index.dox @@ -1,11 +1,150 @@ /** @mainpage Plugin API Documentation - The MariaDB plugin API allows development of plugins that can extend the basic server functionality. + MariaDB Server Plugin API is a C-based extensibility framework + (largely compatible with MySQL’s but extended) that allows dynamic or + static loading of modules to add or modify server behavior without + recompiling the core server. - - Concepts + - @subpage concepts - Get started: Building a plugin - Plugin types - Plugin services - [API reference](api.md#) -*/ \ No newline at end of file +*/ + +/** + @page concepts Plugin API Concepts + + @section concept_big_picture The Big Picture: The server, Plugins and Interfaces + + The server does, at certain stages of its execution, call plugin APIs when it + needs certain operation performed: e.g. authenticate a user, log a message, + read and write from/to a database table etc. + + These API are like written functionality contracts. + They allow separating the server functionality from the actual API + implementations themselves. And, since the API implementions are a dynamic set, + adding new implementations extends the server functionality + (e.g. adds new ways a user can be authenticated or message be logged) + without having to re-compile and even re-start the server itself. + + The MariaDB plugin infrastructure uses the following logical terms: + + @subsection concept_plugin_api Plugin API + + A well defined, versioned and stable interface specification. + It's also abstract, as it's not tied to any one specific implementation. + + @subsection concept_plugin Plugin + + A named and versioned implementation of a specific @ref concept_plugin_api. + + @subsection concept_plugin_library Plugin Library + + (habitually abbreviated as a plugin) + An executable binary that contains one or more @ref concept_plugin that can + be accessed by the server when it needs to call plugin API implementations. + + + @sa @ref implementation on how the above concepts are implemented. +*/ + +/** + @page implementation Plugin API Implementation + + This is how the individual abstract concepts are implemented and + interact with each other. + + @section impl_server The Server Plugin API implementation + + The server is the bedrock of the plugin infrastructure and contains the + base implementation to make use of it. + Plugins can theoretically be loaded into other binaries, but chances are + that they won't operate all that well (if at all) in this case since they + heavily depend on server's infrastructure. + + Here's what the server implements to support plugins: + + @subsection impl_server_global_plugin_list The global plugin list + + The server maintains a global in-memory list of all available plugins (plugin_array), mirrored into a set of hash tables (plugin_hash) and guarded by LOCK_plugin. + + The plugin libraries containing the available plugins can be: + - statically linked into the server binary + - dynamically loaded at startup via the --plugin-load... command line arguments + - dynamically loaded just prior to the server's commencement of normal operations from the mysql.plugins table. + - dynamically loaded at runtime via the INSTALL PLUGIN SQL command. + - unloaded at runtime via the UNINSTALL PLUGIN SQL command + - unloaded at server shutdown + + The server implements all of the above possibilities in its code. + + It also implements and provides a list of interfaces the plugins can use to call back and interact with the server. + These are called @ref impl_server_plugin_services. + + @subsection impl_server_plugin_services Plugin Services Implementation + + The server maintains a global named list of plugin service API implementations. + Every time a @ref concept_plugin_library is initialized, the server gets its global + service API implementation list and sets pointers to each individual API slot into + the empty pointer block provided by the @ref concept_plugin_library. + The library code compiled to call these API pointers can now access + the actual server implementations of these services API. + + @sa @ref plugin_api_services for a list of the services provided by the server. + + @subsection impl_server_plugin_api_call How the server calls a plugin API. + + At certain opportune stages of server's normal operation the server might decide + to "reach out" to a plugin by calling a plugin API. Since the plugins are named it + can call any individual plugin by name. E.g. when executing `CREATE TABLE engine=foo`, + the server will: + + - look "foo" into the cache of plugin "references" (plugin_ref) for that plugin type, if available. + - If no cached reference is found: + - Take LOCK_plugin + - Look "foo" up into the global plugin_array for implementations of the specific plugin API (storage engine in this case) + - If found, create a reference (plugin_ref) to the plugin. + - call API "method" (function pointers) through the plugin_ref, if found. + - when done, either store the plugin_ref into a cache for reuse or release it. + + @section impl_plugin_library The Plugin library Implementation + + A @ref concept_plugin_library is executable code, either a part of + the server itself or bundled as a shared library. + + @subsection impl_plugin_library_static Statically linked plugin libraries. + + Plugins linked statically to the server are collected into a global + server "plugin library" and "installed" (and initialized) at server startup. + + @subsection impl_plugin_library_dynamic Dynamic plugin libraries + + A @ref concept_plugin_library is usually compiled as OS dynamic library: + DLLs on MS Windows, .so on Unixes. + What differentiates a @ref concept_plugin_library from a regular OS + shared library is that it exposes a specific public symbol + _maria_plugin_declarations_ that the server recognizes. + In fact it also exposes _maria_plugin_interface_version_ and + _maria_sizeof_struct_st_plugin_, but these are auxilary. + + _maria_plugin_declarations_ is an array of @ref st_maria_plugin structures, + each describing a @ref concept_plugin this @ref concept_plugin_library provides. + + When the @ref concept_plugin_library is loaded into the server: + * the library is version and maturity checked + * for each @ref concept_plugin contained + * plugin API version check is performed + * the plugin is initialized + * the plugin system and status variables are added to the variable global lists + * the plugin is added into the global plugin_array. + + At unload time the effect of plugin library load above is reversed. + + @section impl_plugin Plugin implementation + + A MariaDB plugin is a logical, versioned implementation of exactly two interfaces: + - The base @ref st_maria_plugin plugin management interface + - A specific plugin interface, one of @ref plugin_types. + */ \ No newline at end of file diff --git a/include/mysql/plugin.h b/include/mysql/plugin.h index b4d1c1c6b54d8..2ace98f85f11a 100644 --- a/include/mysql/plugin.h +++ b/include/mysql/plugin.h @@ -23,7 +23,16 @@ #ifndef MYSQL_PLUGIN_INCLUDED #define MYSQL_PLUGIN_INCLUDED -/* +/** + @defgroup plugin_api Plugin API + The Plugin API is a set of interfaces for handling plugins. + @{ +*/ + +/** + @brief Declaration macros for MySQL plugins. + @ingroup plugin_declaration + On Windows, exports from DLL need to be declared Also, plugin needs to be declared as extern "C" because MSVC unlike other compilers, uses C++ mangling for variables not only @@ -39,6 +48,12 @@ #define MYSQL_DLLEXPORT #endif + +/** + @brief Implementation independent macro for MySQL plugins + @ingroup plugin_declaration + */ + #ifdef __cplusplus #define MYSQL_PLUGIN_EXPORT extern "C" MYSQL_DLLEXPORT #else @@ -55,10 +70,20 @@ typedef struct THD* MYSQL_THD; #endif typedef char my_bool; + +/** + @ingroup plugin_declaration + @brief Opaque type for a plugin handle. + */ typedef void * MYSQL_PLUGIN; #include +/** + @addtogroup plugin_api_service_wsrep + @{ +*/ + #define MYSQL_XIDDATASIZE 128 /** struct st_mysql_xid is binary compatible with the XID structure as @@ -76,28 +101,38 @@ struct st_mysql_xid { }; typedef struct st_mysql_xid MYSQL_XID; +/** @} */ + /************************************************************************* Plugin API. Common for all plugin types. */ +/** + @addtogroup plugin_declaration + @{ +*/ /** MySQL plugin interface version */ #define MYSQL_PLUGIN_INTERFACE_VERSION 0x0105 /** MariaDB plugin interface version */ #define MARIA_PLUGIN_INTERFACE_VERSION 0x0110 -/* - The allowable types of plugins +/** @} */ + +/** + @defgroup plugin_types Plugin Types + The available plugin APIs (types). + @{ */ #define MYSQL_UDF_PLUGIN 0 /**< not implemented */ -#define MYSQL_STORAGE_ENGINE_PLUGIN 1 +#define MYSQL_STORAGE_ENGINE_PLUGIN 1 /**< Storage engine plugin */ #define MYSQL_FTPARSER_PLUGIN 2 /**< Full-text parser plugin */ -#define MYSQL_DAEMON_PLUGIN 3 -#define MYSQL_INFORMATION_SCHEMA_PLUGIN 4 -#define MYSQL_AUDIT_PLUGIN 5 -#define MYSQL_REPLICATION_PLUGIN 6 -#define MYSQL_AUTHENTICATION_PLUGIN 7 -#define MYSQL_MAX_PLUGIN_TYPE_NUM 12 /**< The number of plugin types */ +#define MYSQL_DAEMON_PLUGIN 3 /**< Daemon plugin */ +#define MYSQL_INFORMATION_SCHEMA_PLUGIN 4 /**< Information schema plugin */ +#define MYSQL_AUDIT_PLUGIN 5 /**< Audit plugin */ +#define MYSQL_REPLICATION_PLUGIN 6 /**< Replication plugin */ +#define MYSQL_AUTHENTICATION_PLUGIN 7 /**< Authentication plugin */ +#define MYSQL_MAX_PLUGIN_TYPE_NUM 12 /* MariaDB plugin types */ /** Client and server password validation */ @@ -109,6 +144,14 @@ typedef struct st_mysql_xid MYSQL_XID; /**< Plugins for new native SQL functions */ #define MariaDB_FUNCTION_PLUGIN 11 +/** @} */ + +/** + @defgroup plugin_license Plugin License + @ingroup plugin_declaration + The allowable licenses for plugins + @{ +*/ /* We use the following strings to define licenses for plugins */ #define PLUGIN_LICENSE_PROPRIETARY 0 #define PLUGIN_LICENSE_GPL 1 @@ -117,7 +160,15 @@ typedef struct st_mysql_xid MYSQL_XID; #define PLUGIN_LICENSE_PROPRIETARY_STRING "PROPRIETARY" #define PLUGIN_LICENSE_GPL_STRING "GPL" #define PLUGIN_LICENSE_BSD_STRING "BSD" +/** @} */ + +/** + @defgroup plugin_maturity Plugin Maturity + @ingroup plugin_declaration + The allowable code maturity levels for plugins + @{ +*/ /* definitions of code maturity for plugins */ #define MariaDB_PLUGIN_MATURITY_UNKNOWN 0 #define MariaDB_PLUGIN_MATURITY_EXPERIMENTAL 1 @@ -125,11 +176,16 @@ typedef struct st_mysql_xid MYSQL_XID; #define MariaDB_PLUGIN_MATURITY_BETA 3 #define MariaDB_PLUGIN_MATURITY_GAMMA 4 #define MariaDB_PLUGIN_MATURITY_STABLE 5 +/** @} */ -/* - Macros for beginning and ending plugin declarations. Between - mysql_declare_plugin and mysql_declare_plugin_end there should - be a st_mysql_plugin struct for each plugin to be declared. +/** + @defgroup plugin_declaration Plugin Declaration + How to declare a plugin to the server. + + Macros for beginning and ending plugin declarations. + Between @ref mysql_declare_plugin and @ref mysql_declare_plugin_end + there should be a @ref st_mysql_plugin struct for each plugin to be declared. + @{ */ @@ -181,7 +237,15 @@ MARIA_DECLARE_PLUGIN__(NAME, \ #define mysql_declare_plugin_end ,{0,0,0,0,0,0,0,0,0,0,0,0,0}} #define maria_declare_plugin_end ,{0,0,0,0,0,0,0,0,0,0,0,0,0}} -/* +/** @} */ + +/** + @defgroup plugin_status_vars Plugin Status Variables + @ingroup plugin_declaration + @{ + */ + +/** declarations for SHOW STATUS support in plugins */ enum enum_mysql_show_type @@ -193,11 +257,14 @@ enum enum_mysql_show_type SHOW_SIZE_T, SHOW_always_last }; -/* backward compatibility mapping. */ +/** backward compatibility mapping to SHOW_UINT */ #define SHOW_INT SHOW_UINT +/** backward compatibility mapping to SHOW_ULONG */ #define SHOW_LONG SHOW_ULONG +/** backward compatibility mapping to SHOW_ULONGLONG */ #define SHOW_LONGLONG SHOW_ULONGLONG +/** SHOW STATUS scope */ enum enum_var_type { SHOW_OPT_DEFAULT= 0, SHOW_OPT_SESSION, SHOW_OPT_GLOBAL, SHOW_OPT_SESSION_NO_LOCK @@ -226,17 +293,26 @@ struct st_mysql_show_var SHOW_FUNC_ENTRY(const char *name, return tmp; }; +/** @} */ -/* + +/** + @defgroup plugin_flags Plugin Flags + @ingroup plugin_declaration Constants for plugin flags. + @{ */ #define PLUGIN_OPT_NO_INSTALL 1UL /**< Not dynamically loadable */ #define PLUGIN_OPT_NO_UNINSTALL 2UL /**< Not dynamically unloadable */ +/** @} */ -/* - declarations for server variables and command line options +/** + @defgroup plugin_sys_vars Plugin System Variables + @ingroup plugin_declaration + Declarations for server variables and command line options. + @{ */ @@ -263,16 +339,13 @@ struct st_mysql_sys_var; struct st_mysql_value; /** - SYNOPSIS - (*mysql_var_check_func)() - thd thread handle - var dynamic variable being altered - save pointer to temporary storage - value user provided value - RETURN - 0 user provided value is OK and the update func may be called. - any other value indicates error. - + @param thd thread handle + @param var dynamic variable being altered + @param save pointer to temporary storage + @param value user provided value + @retval 0 user provided value is OK and the update func may be called. + @retval any other value indicates error. + This function should parse the user provided value and store in the provided temporary storage any data as required by the update func. There is sufficient space in the temporary storage to store a double. @@ -286,14 +359,10 @@ typedef int (*mysql_var_check_func)(MYSQL_THD thd, void *save, struct st_mysql_value *value); /** - SYNOPSIS - (*mysql_var_update_func)() - thd thread handle - var dynamic variable being altered - var_ptr pointer to dynamic variable - save pointer to temporary storage - RETURN - NONE + @param thd thread handle + @param var dynamic variable being altered + @param var_ptr pointer to dynamic variable + @param save pointer to temporary storage This function should use the validated value stored in the temporary store and persist it in the provided pointer to the dynamic variable. @@ -304,8 +373,11 @@ typedef void (*mysql_var_update_func)(MYSQL_THD thd, void *var_ptr, const void *save); -/* the following declarations are for internal use only */ - +/** + @defgroup internal_plugin_vars Internal Only declarations for plugin system variables + The following declarations are for internal use only + @{ +*/ #define PLUGIN_VAR_MASK \ (PLUGIN_VAR_READONLY | PLUGIN_VAR_NOSYSVAR | \ @@ -383,10 +455,7 @@ typedef void (*mysql_var_update_func)(MYSQL_THD thd, TYPELIB *typelib; \ } MYSQL_SYSVAR_NAME(name) - -/* - the following declarations are for use by plugin implementors -*/ +/** @} */ #define MYSQL_SYSVAR_BOOL(name, varname, opt, comment, check, update, def) \ DECLARE_MYSQL_SYSVAR_BASIC(name, char) = { \ @@ -529,9 +598,11 @@ DECLARE_MYSQL_THDVAR_SIMPLE(name, double) = { \ #define THDVAR(thd, name) \ (*(MYSQL_SYSVAR_NAME(name).resolve(thd, MYSQL_SYSVAR_NAME(name).offset))) + /** @} */ /** - Plugin description structure. + @brief Plugin description structure. + @ingroup plugin_declaration */ struct st_mysql_plugin @@ -558,7 +629,8 @@ struct st_mysql_plugin }; /** - MariaDB extension for plugins declaration structure. + @brief MariaDB extension for plugins declaration structure. + @ingroup plugin_declaration It also copies current MySQL plugin fields to have more independency in plugins extension @@ -592,16 +664,18 @@ struct st_maria_plugin */ #include "plugin_ftparser.h" -/************************************************************************* - API for Storage Engine plugin. (MYSQL_DAEMON_PLUGIN) +/** + @defgroup daemon_plugin_data Daemon Plugin + @ingroup plugin_types + API for Storage Engine plugin. (@ref MYSQL_DAEMON_PLUGIN) + @{ */ -/* daemon plugins of different MySQL releases are incompatible */ +/** daemon plugins of different MySQL releases are incompatible */ #define MYSQL_DAEMON_INTERFACE_VERSION (MYSQL_VERSION_ID << 8) -/* - Here we define only the descriptor structure, that is referred from - st_mysql_plugin. +/** + The descriptor structure, that is referred from st_mysql_plugin. */ struct st_mysql_daemon @@ -609,17 +683,20 @@ struct st_mysql_daemon int interface_version; }; +/** @} */ -/************************************************************************* - API for I_S plugin. (MYSQL_INFORMATION_SCHEMA_PLUGIN) +/** + @defgroup information_schema_plugin_data Information Schema Plugin + @ingroup plugin_types + API for I_S plugin. (@ref MYSQL_INFORMATION_SCHEMA_PLUGIN) + @{ */ -/* information schema plugins different MySQL releases are incompatible */ +/** information schema plugins of different MySQL releases are incompatible */ #define MYSQL_INFORMATION_SCHEMA_INTERFACE_VERSION (MYSQL_VERSION_ID << 8) -/* - Here we define only the descriptor structure, that is referred from - st_mysql_plugin. +/** + The descriptor structure, that is referred from st_mysql_plugin. */ struct st_mysql_information_schema @@ -627,18 +704,23 @@ struct st_mysql_information_schema int interface_version; }; +/** @} */ -/************************************************************************* - API for Storage Engine plugin. (MYSQL_STORAGE_ENGINE_PLUGIN) + +/** + @defgroup storage_engine_plugin_data Storage Engine Plugin + @ingroup plugin_types + API for Storage Engine plugin. (@ref MYSQL_STORAGE_ENGINE_PLUGIN) + @{ */ -/* storage engines of different MySQL releases are incompatible */ +/** storage engines of different MySQL releases are incompatible */ #define MYSQL_HANDLERTON_INTERFACE_VERSION (MYSQL_VERSION_ID << 8) -/* - The real API is in the sql/handler.h - Here we define only the descriptor structure, that is referred from - st_mysql_plugin. +/** + The real API is in the sql/handler.h + Here we define only the descriptor structure, that is referred from + st_mysql_plugin. */ struct st_mysql_storage_engine @@ -648,9 +730,13 @@ struct st_mysql_storage_engine struct transaction_participant; +/** @} */ -/* - API for Replication plugin. (MYSQL_REPLICATION_PLUGIN) +/** + @defgroup replication_plugin_data Replication Plugin + @ingroup plugin_types + API for Replication plugin. (@ref MYSQL_REPLICATION_PLUGIN) + @{ */ #define MYSQL_REPLICATION_INTERFACE_VERSION 0x0200 @@ -661,11 +747,18 @@ struct transaction_participant; int interface_version; }; +/** @} */ + +/** + @addtogroup plugin_sys_vars + @{ +*/ + #define MYSQL_VALUE_TYPE_STRING 0 #define MYSQL_VALUE_TYPE_REAL 1 #define MYSQL_VALUE_TYPE_INT 2 -/************************************************************************* +/** st_mysql_value struct for reading values from mysqld. Used by server variables framework to parse user-provided values. Will be used for arguments when implementing UDFs. @@ -684,10 +777,16 @@ struct st_mysql_value int (*is_unsigned)(struct st_mysql_value *); }; +/** @} */ -/************************************************************************* - Miscellaneous functions for plugin implementors -*/ +/** + @defgroup plugin_api_service_direct Services for direct access to server internals + @ingroup plugin_api_services_for_plugins + + These are callbacks to the server that circumvent the normal plugin service APIs + + @{ + */ #ifdef __cplusplus extern "C" { @@ -725,6 +824,10 @@ int mysql_tmpfile(const char *prefix); */ unsigned long thd_get_thread_id(const MYSQL_THD thd); +/** + @addtogroup plugin_api_service_wsrep + @{ +*/ /** Get the XID for this connection's transaction @@ -733,6 +836,8 @@ unsigned long thd_get_thread_id(const MYSQL_THD thd); */ void thd_get_xid(const MYSQL_THD thd, MYSQL_XID *xid); +/** @} */ + /** Invalidate the query cache for a given table. @@ -810,9 +915,21 @@ void thd_set_ha_data(MYSQL_THD thd, const struct transaction_participant *hton, */ void thd_wakeup_subsequent_commits(MYSQL_THD thd, int wakeup_error); +/** @} */ + #ifdef __cplusplus } #endif +/** + @defgroup plugin_api_services_for_plugins Services for plugins + Plugins calling back into the server. + + If you need to call back into the server from a plugin, you should use the services + provided in this section. + */ + +/** @} */ + #endif diff --git a/include/mysql/plugin_audit.h b/include/mysql/plugin_audit.h index be83c7e02f73f..69d140ed46067 100644 --- a/include/mysql/plugin_audit.h +++ b/include/mysql/plugin_audit.h @@ -17,12 +17,16 @@ #ifndef _my_audit_h #define _my_audit_h -/************************************************************************* - API for Audit plugin. (MYSQL_AUDIT_PLUGIN) -*/ #include "plugin.h" +/** + @defgroup audit_plugin_data Audit Plugin + @ingroup plugin_types + API for Audit plugin. (@ref MYSQL_AUDIT_PLUGIN) + @{ +*/ + #ifdef __cplusplus extern "C" { #endif @@ -32,14 +36,15 @@ extern "C" { #define MYSQL_AUDIT_INTERFACE_VERSION 0x0303 -/************************************************************************* - AUDIT CLASS : GENERAL +/** + @defgroup audit_general_class AUDIT CLASS : GENERAL LOG events occurs before emitting to the general query log. ERROR events occur before transmitting errors to the user. RESULT events occur after transmitting a resultset to the user. STATUS events occur after transmitting a resultset or errors to the user. + @{ */ #define MYSQL_AUDIT_GENERAL_CLASS 0 @@ -71,13 +76,15 @@ struct mysql_event_general MYSQL_CONST_LEX_STRING database; }; +/** @} */ + +/** + @defgroup audit_connection_class AUDIT CLASS : CONNECTION -/* - AUDIT CLASS : CONNECTION - CONNECT occurs after authentication phase is completed. DISCONNECT occurs after connection is terminated. CHANGE_USER occurs after COM_CHANGE_USER RPC is completed. + @{ */ #define MYSQL_AUDIT_CONNECTION_CLASS 1 @@ -110,9 +117,11 @@ struct mysql_event_connection unsigned int tls_version_length; }; -/* - AUDIT CLASS : TABLE - +/** @} */ + +/** + @defgroup audit_table_class AUDIT CLASS : TABLE + LOCK occurs when a connection "locks" (this does not necessarily mean a table lock and also happens for row-locking engines) the table at the beginning of a statement. This event is generated at the beginning of every statement for @@ -121,6 +130,8 @@ struct mysql_event_connection the tables are unlocked). CREATE/DROP/RENAME occur when a table is created, dropped, or renamed. + + @{ */ #define MYSQL_AUDIT_TABLE_CLASS 15 @@ -154,9 +165,10 @@ struct mysql_event_table unsigned long long query_id; }; -/************************************************************************* - Here we define the descriptor structure, that is referred from - st_mysql_plugin. +/** @} */ + +/** + The descriptor structure, that is referred from @ref st_mysql_plugin. release_thd() event occurs when the event class consumer is to be disassociated from the specified THD. This would typically occur @@ -185,4 +197,5 @@ struct st_mysql_audit } #endif +/** @} */ #endif diff --git a/include/mysql/plugin_auth.h b/include/mysql/plugin_auth.h index 84dc83b1ad337..8cd27ca45d170 100644 --- a/include/mysql/plugin_auth.h +++ b/include/mysql/plugin_auth.h @@ -21,8 +21,14 @@ Authentication Plugin API. This file defines the API for server authentication plugins. + + @defgroup authentication_plugin Authentication Plugin + @ingroup plugin_types + API for Authentication plugin. (@ref MYSQL_AUTHENTICATION_PLUGIN) + @{ */ + #define MYSQL_PLUGIN_AUTH_INCLUDED #include @@ -35,12 +41,16 @@ extern "C" { #endif -/* defines for MYSQL_SERVER_AUTH_INFO.password_used */ +/** + @defgroup authentication_plugin_password_used Values for st_mysql_server_auth_info.password_used + @{ +*/ #define PASSWORD_USED_NO 0 #define PASSWORD_USED_YES 1 #define PASSWORD_USED_NO_MENTION 2 +/** @} */ /** Provides server plugin access to authentication information @@ -86,12 +96,15 @@ typedef struct st_mysql_server_auth_info char external_user[MYSQL_USERNAME_LENGTH+1]; /** - This only affects the "Authentication failed. Password used: %s" - error message. has the following values : - 0 : %s will be NO. - 1 : %s will be YES. - 2 : there will be no %s. + This only affects the "Authentication failed. Password used: @%s" + error message. has the following values: + - PASSWORD_USED_NO: @%s will be NO. + - PASSWORD_USED_YES: @%s will be YES. + - PASSWORD_USED_NO_MENTION: there will be no @%s. + Set it as appropriate or ignore at will. + + @sa authentication_plugin_password_used */ int password_used; @@ -179,5 +192,7 @@ struct st_mysql_auth } #endif +/** @} */ + #endif diff --git a/include/mysql/plugin_auth_common.h b/include/mysql/plugin_auth_common.h index c57850bb7d31f..2ac74ff216ccb 100644 --- a/include/mysql/plugin_auth_common.h +++ b/include/mysql/plugin_auth_common.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_PLUGIN_AUTH_COMMON_INCLUDED /* Copyright (C) 2010 Sergei Golubchik and Monty Program Ab Copyright (c) 2010, Oracle and/or its affiliates. @@ -15,6 +14,9 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_PLUGIN_AUTH_COMMON_INCLUDED +#define MYSQL_PLUGIN_AUTH_COMMON_INCLUDED + #ifdef _WIN32 #include #endif @@ -25,13 +27,18 @@ This file defines constants and data structures that are the same for both client- and server-side authentication plugins. */ -#define MYSQL_PLUGIN_AUTH_COMMON_INCLUDED + +/** + @addtogroup authentication_plugin + @{ +*/ /** the max allowed length for a user name */ #define MYSQL_USERNAME_LENGTH 512 /** - return values of the plugin authenticate_user() method. + @defgroup authentication_plugin_return_codes Return codes for the plugin authenticate_user() method + @{ */ /** @@ -90,6 +97,7 @@ */ #define CR_OK_HANDSHAKE_COMPLETE -2 +/** @} */ typedef struct st_plugin_vio_info { enum { MYSQL_VIO_INVALID, MYSQL_VIO_TCP, MYSQL_VIO_SOCKET, @@ -130,5 +138,7 @@ typedef struct st_plugin_vio } MYSQL_PLUGIN_VIO; +/** @} */ + #endif diff --git a/include/mysql/plugin_data_type.h b/include/mysql/plugin_data_type.h index 77aa9fb27a2dd..9d20f089ed999 100644 --- a/include/mysql/plugin_data_type.h +++ b/include/mysql/plugin_data_type.h @@ -27,22 +27,29 @@ #include -/* - API for data type plugins. (MariaDB_DATA_TYPE_PLUGIN) +/** + @defgroup data_type_plugin Data Type Plugin + @ingroup plugin_types + API for data type plugins. (@ref MariaDB_DATA_TYPE_PLUGIN) + @{ +*/ + +/** + Data type plugin descriptor */ #define MariaDB_DATA_TYPE_INTERFACE_VERSION (MYSQL_VERSION_ID << 8) +/** + Data type plugin descriptor +*/ struct st_mariadb_data_type { int interface_version; class Type_handler *type_handler; }; - -/** - Data type plugin descriptor -*/ +/** @} */ #endif /* __cplusplus */ diff --git a/include/mysql/plugin_encryption.h b/include/mysql/plugin_encryption.h index 494e010e48110..96f0a2bf7f51a 100644 --- a/include/mysql/plugin_encryption.h +++ b/include/mysql/plugin_encryption.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_PLUGIN_ENCRYPTION_INCLUDED /* Copyright (C) 2014, 2015 Sergei Golubchik and MariaDB This program is free software; you can redistribute it and/or modify @@ -14,6 +13,9 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_PLUGIN_ENCRYPTION_INCLUDED +#define MYSQL_PLUGIN_ENCRYPTION_INCLUDED + /** @file @@ -23,7 +25,23 @@ keys for MariaDB on-disk data encryption. */ -#define MYSQL_PLUGIN_ENCRYPTION_INCLUDED +/** + @defgroup encryption_plugin_data Encryption Plugin + @ingroup plugin_types + API for Encryption plugin. (@ref MariaDB_ENCRYPTION_PLUGIN) + + The API for server plugins that manage encryption + keys for MariaDB on-disk data encryption + + The caller uses encryption as follows: + 1. create the encryption context object of the crypt_ctx_size() bytes. + 2. initialize it with crypt_ctx_init(). + 3. repeat crypt_ctx_update() until there are no more data to encrypt. + 4. write the remaining output bytes and destroy the context object + with crypt_ctx_finish(). + @{ +*/ + #include @@ -72,15 +90,7 @@ struct st_mariadb_encryption unsigned int (*get_key)(unsigned int key_id, unsigned int version, unsigned char *key, unsigned int *key_length); - /*********** ENCRYPTION ************************************************/ - /* - the caller uses encryption as follows: - 1. create the encryption context object of the crypt_ctx_size() bytes. - 2. initialize it with crypt_ctx_init(). - 3. repeat crypt_ctx_update() until there are no more data to encrypt. - 4. write the remaining output bytes and destroy the context object - with crypt_ctx_finish(). - */ + /*********** ENCRYPTION CONTEXT *****************************************/ /** returns the size of the encryption context object in bytes @@ -125,4 +135,6 @@ struct st_mariadb_encryption #ifdef __cplusplus } #endif + +/** @} */ #endif diff --git a/include/mysql/plugin_ftparser.h b/include/mysql/plugin_ftparser.h index 511b34bb234dd..6965afc412cce 100644 --- a/include/mysql/plugin_ftparser.h +++ b/include/mysql/plugin_ftparser.h @@ -18,21 +18,25 @@ #define _my_plugin_ftparser_h #include "plugin.h" +/** + @defgroup ftparser_plugin_data Full-text Parser Plugin + @ingroup plugin_types + API for Full-text parser plugin. (@ref MYSQL_FTPARSER_PLUGIN) + @{ +*/ #ifdef __cplusplus extern "C" { #endif -/************************************************************************* - API for Full-text parser plugin. (MYSQL_FTPARSER_PLUGIN) -*/ - #define MYSQL_FTPARSER_INTERFACE_VERSION 0x0100 -/* Parsing modes. Set in MYSQL_FTPARSER_PARAM::mode */ +/** Parsing modes. Set in MYSQL_FTPARSER_PARAM::mode */ enum enum_ftparser_mode { -/* - Fast and simple mode. This mode is used for indexing, and natural +/** + Fast and simple mode. + + This mode is used for indexing, and natural language queries. The parser is expected to return only those words that go into the @@ -41,9 +45,10 @@ enum enum_ftparser_mode */ MYSQL_FTPARSER_SIMPLE_MODE= 0, -/* - Parse with stopwords mode. This mode is used in boolean searches for - "phrase matching." +/** + Parse with stopwords mode. + + This mode is used in boolean searches for "phrase matching." The parser is not allowed to ignore words in this mode. Every word should be returned, including stopwords and words that are too short @@ -52,8 +57,10 @@ enum enum_ftparser_mode */ MYSQL_FTPARSER_WITH_STOPWORDS= 1, -/* - Parse in boolean mode. This mode is used to parse a boolean query string. +/** + Parse in boolean mode. + + This mode is used to parse a boolean query string. The parser should provide a valid MYSQL_FTPARSER_BOOLEAN_INFO structure in the 'boolean_info' argument to mysql_add_word(). @@ -66,70 +73,80 @@ enum enum_ftparser_mode MYSQL_FTPARSER_FULL_BOOLEAN_INFO= 2 }; -/* - Token types for boolean mode searching (used for the type member of - MYSQL_FTPARSER_BOOLEAN_INFO struct) - - FT_TOKEN_EOF: End of data. - FT_TOKEN_WORD: Regular word. - FT_TOKEN_LEFT_PAREN: Left parenthesis (start of group/sub-expression). - FT_TOKEN_RIGHT_PAREN: Right parenthesis (end of group/sub-expression). - FT_TOKEN_STOPWORD: Stopword. +/** + Token types for boolean mode searching + + Used for the type member of MYSQL_FTPARSER_BOOLEAN_INFO struct. */ enum enum_ft_token_type { - FT_TOKEN_EOF= 0, - FT_TOKEN_WORD= 1, - FT_TOKEN_LEFT_PAREN= 2, - FT_TOKEN_RIGHT_PAREN= 3, - FT_TOKEN_STOPWORD= 4 + FT_TOKEN_EOF= 0, /**< End of data. */ + FT_TOKEN_WORD= 1, /**< Regular word. */ + FT_TOKEN_LEFT_PAREN= 2, /**< Left parenthesis (start of group/sub-expression). */ + FT_TOKEN_RIGHT_PAREN= 3, /**< Right parenthesis (end of group/sub-expression). */ + FT_TOKEN_STOPWORD= 4 /**< Stopword. */ }; -/* +/** + Structure for boolean mode search. + This structure is used in boolean search mode only. It conveys boolean-mode metadata to the MySQL search engine for every word in the search query. A valid instance of this structure must be filled in by the plugin parser and passed as an argument in the call to mysql_add_word (the callback function in the MYSQL_FTPARSER_PARAM structure) when a query is parsed in boolean mode. - - type: The token type. Should be one of the enum_ft_token_type values. - - yesno: Whether the word must be present for a match to occur: - >0 Must be present - <0 Must not be present - 0 Neither; the word is optional but its presence increases the relevance - With the default settings of the ft_boolean_syntax system variable, - >0 corresponds to the '+' operator, <0 corresponds to the '-' operator, - and 0 means neither operator was used. - - weight_adjust: A weighting factor that determines how much a match - for the word counts. Positive values increase, negative - decrease the - relative word's importance in the query. - - wasign: The sign of the word's weight in the query. If it's non-negative - the match for the word will increase document relevance, if it's - negative - decrease (the word becomes a "noise word", the less of it the - better). - - trunc: Corresponds to the '*' operator in the default setting of the - ft_boolean_syntax system variable. */ typedef struct st_mysql_ftparser_boolean_info { + /** The token type. Should be one of the enum_ft_token_type values. */ enum enum_ft_token_type type; + /** + Whether the word must be present for a match to occur + + - `>0` Must be present + - `<0` Must not be present + - `0` Neither; the word is optional but its presence increases the relevance + + With the default settings of the `ft_boolean_syntax` system variable, + `>0` corresponds to the '+' operator, `<0` corresponds to the '-' operator, + and `0` means neither operator was used. + */ int yesno; + /** + A weighting factor that determines how much a match + for the word counts. + + Positive values increase, negative - decrease the + relative word's importance in the query. + */ int weight_adjust; + + /** + The sign of the word's weight in the query. + + If it's non-negative + the match for the word will increase document relevance, if it's + negative - decrease (the word becomes a "noise word", the less of it the + better). + */ char wasign; + /** + Corresponds to the `*` operator in the default setting of the + `ft_boolean_syntax` system variable. + */ char trunc; - /* These are parser state and must be removed. */ + /** Parser state. Must be removed. */ char prev; + /** Parser state. Must be removed. */ char *quot; } MYSQL_FTPARSER_BOOLEAN_INFO; -/* +/** + Needs a copy flag. + The following flag means that buffer with a string (document, word) may be overwritten by the caller before the end of the parsing (that is before st_mysql_ftparser::deinit() call). If one needs the string @@ -141,66 +158,82 @@ typedef struct st_mysql_ftparser_boolean_info */ #define MYSQL_FTFLAGS_NEED_COPY 1 -/* - An argument of the full-text parser plugin. This structure is - filled in by MySQL server and passed to the parsing function of the +/** + An argument of the full-text parser plugin. + + This structure is filled in by MySQL server and passed to the parsing function of the plugin as an in/out parameter. - - mysql_parse: A pointer to the built-in parser implementation of the - server. It's set by the server and can be used by the parser plugin - to invoke the MySQL default parser. If plugin's role is to extract - textual data from .doc, .pdf or .xml content, it might extract - plaintext from the content, and then pass the text to the default - MySQL parser to be parsed. - - mysql_add_word: A server callback to add a new word. When parsing - a document, the server sets this to point at a function that adds - the word to MySQL full-text index. When parsing a search query, - this function will add the new word to the list of words to search - for. The boolean_info argument can be NULL for all cases except - when mode is MYSQL_FTPARSER_FULL_BOOLEAN_INFO. A plugin can replace this - callback to post-process every parsed word before passing it to the original - mysql_add_word function. - - ftparser_state: A generic pointer. The plugin can set it to point - to information to be used internally for its own purposes. - - mysql_ftparam: This is set by the server. It is used by MySQL functions - called via mysql_parse() and mysql_add_word() callback. The plugin - should not modify it. - - cs: Information about the character set of the document or query string. - - doc: A pointer to the document or query string to be parsed. - - length: Length of the document or query string, in bytes. - - flags: See MYSQL_FTFLAGS_* constants above. - - mode: The parsing mode. With boolean operators, with stopwords, or - nothing. See enum_ftparser_mode above. */ - typedef struct st_mysql_ftparser_param { + /** + A pointer to the built-in parser implementation of the + server. + + It's set by the server and can be used by the parser plugin + to invoke the MySQL default parser. If plugin's role is to extract + textual data from .doc, .pdf or .xml content, it might extract + plaintext from the content, and then pass the text to the default + MySQL parser to be parsed. + */ int (*mysql_parse)(struct st_mysql_ftparser_param *, const char *doc, int doc_len); + /** + A server callback to add a new word. + + When parsing a document, the server sets this to point at a function that adds + the word to MySQL full-text index. When parsing a search query, + this function will add the new word to the list of words to search + for. The boolean_info argument can be NULL for all cases except + when mode is MYSQL_FTPARSER_FULL_BOOLEAN_INFO. A plugin can replace this + callback to post-process every parsed word before passing it to the original + add_word function. + */ int (*mysql_add_word)(struct st_mysql_ftparser_param *, const char *word, int word_len, MYSQL_FTPARSER_BOOLEAN_INFO *boolean_info); + /** + A generic pointer. + + The plugin can set it to point + to information to be used internally for its own purposes. + */ void *ftparser_state; + /** + This is set by the server. + + It is used by MySQL functions + called via mysql_parse() and mysql_add_word() callback. The plugin + should not modify it. + */ void *mysql_ftparam; + /** + Information about the character set of the document or query string. + */ const struct charset_info_st *cs; + /** + A pointer to the document or query string to be parsed. + */ const char *doc; + /** + Length of the document or query string, in bytes. + */ int length; + /** + Flags for the parser. @sa MYSQL_FTFLAGS_NEED_COPY + */ unsigned int flags; + /** + The parsing mode. With boolean operators, with stopwords, or + nothing. @sa enum_ftparser_mode. + */ enum enum_ftparser_mode mode; } MYSQL_FTPARSER_PARAM; /* Full-text parser descriptor. - interface_version is, e.g., MYSQL_FTPARSER_INTERFACE_VERSION. + interface_version is, e.g., @ref MYSQL_FTPARSER_INTERFACE_VERSION. The parsing, initialization, and deinitialization functions are invoked per SQL statement for which the parser is used. */ @@ -218,5 +251,7 @@ struct st_mysql_ftparser } #endif +/** @} */ + #endif diff --git a/include/mysql/plugin_function.h b/include/mysql/plugin_function.h index 117acd43222ef..2177973e2582b 100644 --- a/include/mysql/plugin_function.h +++ b/include/mysql/plugin_function.h @@ -23,12 +23,20 @@ This file defines the API for server plugins that manage functions. */ +/** + @defgroup function_plugin_data Function Plugin + @ingroup plugin_types + API for Function plugin. (@ref MariaDB_FUNCTION_INTERFACE_VERSION) + + This file defines the API for server plugins that manage functions. + @{ +*/ #ifdef __cplusplus #include -/* - API for function plugins. (MariaDB_FUNCTION_PLUGIN) +/** + API for function plugins. */ #define MariaDB_FUNCTION_INTERFACE_VERSION (MYSQL_VERSION_ID << 8) @@ -51,4 +59,6 @@ class Plugin_function #endif /* __cplusplus */ +/** @} */ + #endif /* MARIADB_PLUGIN_FUNCTION_INCLUDED */ diff --git a/include/mysql/plugin_password_validation.h b/include/mysql/plugin_password_validation.h index 94d6c63967fec..1d8bd89506e6a 100644 --- a/include/mysql/plugin_password_validation.h +++ b/include/mysql/plugin_password_validation.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_PLUGIN_PASSWORD_VALIDATION_INCLUDED /* Copyright (C) 2014 Sergei Golubchik and MariaDB This program is free software; you can redistribute it and/or modify @@ -14,6 +13,9 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_PLUGIN_PASSWORD_VALIDATION_INCLUDED +#define MYSQL_PLUGIN_PASSWORD_VALIDATION_INCLUDED + /** @file @@ -22,10 +24,18 @@ This file defines the API for server password validation plugins. */ -#define MYSQL_PLUGIN_PASSWORD_VALIDATION_INCLUDED #include +/** + @defgroup password_validation_plugin_data Password Validation Plugin + @ingroup plugin_types + Password validation plugin API (@ref MariaDB_PASSWORD_VALIDATION_INTERFACE_VERSION) + + This file defines the API for server plugins that perform password validation. + @{ +*/ + #ifdef __cplusplus extern "C" { #endif @@ -51,5 +61,7 @@ struct st_mariadb_password_validation } #endif +/** @} */ + #endif diff --git a/include/mysql/psi/mysql_file.h b/include/mysql/psi/mysql_file.h index 36d073c32e233..4aa36675c729a 100644 --- a/include/mysql/psi/mysql_file.h +++ b/include/mysql/psi/mysql_file.h @@ -48,16 +48,16 @@ #include "mysql/psi/psi.h" -#ifndef PSI_FILE_CALL -#define PSI_FILE_CALL(M) PSI_DYNAMIC_CALL(M) -#endif - /** @defgroup File_instrumentation File Instrumentation @ingroup Instrumentation_interface @{ */ +#ifndef PSI_FILE_CALL +#define PSI_FILE_CALL(M) PSI_DYNAMIC_CALL(M) +#endif + /** @def mysql_file_register(P1, P2, P3) File registration. diff --git a/include/mysql/psi/mysql_idle.h b/include/mysql/psi/mysql_idle.h index dc7f5180285eb..63b3b16d6df8c 100644 --- a/include/mysql/psi/mysql_idle.h +++ b/include/mysql/psi/mysql_idle.h @@ -27,6 +27,10 @@ /** @file mysql/psi/mysql_idle.h Instrumentation helpers for idle waits. + + @defgroup Idle_instrumentation Idle Instrumentation + @ingroup Instrumentation_interface + @{ */ #include "mysql/psi/psi.h" @@ -35,12 +39,6 @@ #define PSI_IDLE_CALL(M) PSI_DYNAMIC_CALL(M) #endif -/** - @defgroup Idle_instrumentation Idle Instrumentation - @ingroup Instrumentation_interface - @{ -*/ - /** @def MYSQL_START_IDLE_WAIT Instrumentation helper for table io_waits. diff --git a/include/mysql/psi/mysql_mdl.h b/include/mysql/psi/mysql_mdl.h index 752173b7e9614..1249d82683800 100644 --- a/include/mysql/psi/mysql_mdl.h +++ b/include/mysql/psi/mysql_mdl.h @@ -26,6 +26,13 @@ /** @file mysql/psi/mysql_mdl.h Instrumentation helpers for metadata locks. + + @defgroup Metadata_instrumentation Metadata Instrumentation + @ingroup Instrumentation_interface + + Instrumentation helpers for metadata locks. + + @{ */ #include "mysql/psi/psi.h" @@ -49,12 +56,6 @@ #define PSI_CALL_destroy_metadata_lock(A) do {} while(0) #endif -/** - @defgroup Metadata_instrumentation Metadata Instrumentation - @ingroup Instrumentation_interface - @{ -*/ - /** @def mysql_mdl_create(K, M, A) Instrumented metadata lock creation. diff --git a/include/mysql/psi/mysql_memory.h b/include/mysql/psi/mysql_memory.h index 7f54b00d6fe73..b236b42187472 100644 --- a/include/mysql/psi/mysql_memory.h +++ b/include/mysql/psi/mysql_memory.h @@ -20,14 +20,19 @@ along with this program; if not, write to the Free Software Foundation, 51 Franklin Street, Suite 500, Boston, MA 02110-1335 USA */ -#ifndef MYSQL_MEMORY_H -#define MYSQL_MEMORY_H - /** @file mysql/psi/mysql_memory.h Instrumentation helpers for memory allocation. */ +#ifndef MYSQL_MEMORY_H +/** + @defgroup Memory_instrumentation Memory Instrumentation + @ingroup Instrumentation_interface + @{ +*/ +#define MYSQL_MEMORY_H + #include "mysql/psi/psi.h" #ifdef HAVE_PSI_MEMORY_INTERFACE @@ -46,12 +51,6 @@ #define PSI_MEMORY_CALL(M) PSI_DYNAMIC_CALL(M) #endif -/** - @defgroup Memory_instrumentation Memory Instrumentation - @ingroup Instrumentation_interface - @{ -*/ - /** @def mysql_memory_register(P1, P2, P3) Memory registration. diff --git a/include/mysql/psi/mysql_ps.h b/include/mysql/psi/mysql_ps.h index 89f34ef63f7a1..4013337ae369b 100644 --- a/include/mysql/psi/mysql_ps.h +++ b/include/mysql/psi/mysql_ps.h @@ -26,6 +26,13 @@ /** @file mysql/psi/mysql_ps.h Instrumentation helpers for prepared statements. + + @defgroup Prepared_statements_instrumentation Prepared Statements Instrumentation + @ingroup Instrumentation_interface + + Instrumentation helpers for prepared statements. + + @{ */ #include "mysql/psi/psi.h" @@ -105,4 +112,6 @@ inline_mysql_set_prepared_stmt_text(PSI_prepared_stmt *prepared_stmt, } #endif +/** @} */ + #endif diff --git a/include/mysql/psi/mysql_socket.h b/include/mysql/psi/mysql_socket.h index fee21d63a24bb..9498eb3f171b2 100644 --- a/include/mysql/psi/mysql_socket.h +++ b/include/mysql/psi/mysql_socket.h @@ -26,6 +26,18 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA #ifndef MYSQL_SOCKET_H #define MYSQL_SOCKET_H +/** + @file mysql/psi/mysql_socket.h +[...] +*/ + +/** + @defgroup Socket_instrumentation Socket Instrumentation + @ingroup Instrumentation_interface + @{ +*/ + + /* For MY_STAT */ #include /* For my_chsize */ @@ -40,10 +52,6 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA #include #define SOCKBUF_T void #endif -/** - @file mysql/psi/mysql_socket.h -[...] -*/ #include "mysql/psi/psi.h" @@ -51,12 +59,6 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA #define PSI_SOCKET_CALL(M) PSI_DYNAMIC_CALL(M) #endif -/** - @defgroup Socket_instrumentation Socket Instrumentation - @ingroup Instrumentation_interface - @{ -*/ - /** @def mysql_socket_register(P1, P2, P3) Socket registration. diff --git a/include/mysql/psi/mysql_sp.h b/include/mysql/psi/mysql_sp.h index c25247459ae81..29ab885ea2a4e 100644 --- a/include/mysql/psi/mysql_sp.h +++ b/include/mysql/psi/mysql_sp.h @@ -26,6 +26,13 @@ /** @file mysql/psi/mysql_sp.h Instrumentation helpers for stored programs. + + @defgroup Stored_programs_instrumentation Stored Programs Instrumentation + @ingroup Instrumentation_interface + + Instrumentation helpers for stored programs. + + @{ */ #include "mysql/psi/psi.h" @@ -101,4 +108,6 @@ inline_mysql_get_sp_share(uint sp_type, } #endif +/** @} */ + #endif diff --git a/include/mysql/psi/mysql_stage.h b/include/mysql/psi/mysql_stage.h index b6bc5ce370653..6ec30131b31e4 100644 --- a/include/mysql/psi/mysql_stage.h +++ b/include/mysql/psi/mysql_stage.h @@ -26,6 +26,10 @@ /** @file mysql/psi/mysql_stage.h Instrumentation helpers for stages. + + @defgroup Stage_instrumentation Stage Instrumentation + @ingroup Instrumentation_interface + @{ */ #include "mysql/psi/psi.h" @@ -34,12 +38,6 @@ #define PSI_STAGE_CALL(M) PSI_DYNAMIC_CALL(M) #endif -/** - @defgroup Stage_instrumentation Stage Instrumentation - @ingroup Instrumentation_interface - @{ -*/ - /** @def mysql_stage_register(P1, P2, P3) Stage registration. diff --git a/include/mysql/psi/mysql_statement.h b/include/mysql/psi/mysql_statement.h index 544bba678857f..fb80e8188196a 100644 --- a/include/mysql/psi/mysql_statement.h +++ b/include/mysql/psi/mysql_statement.h @@ -29,6 +29,12 @@ Instrumentation helpers for statements. */ +/** + @defgroup Statement_instrumentation Statement Instrumentation + @ingroup Instrumentation_interface + @{ +*/ + #include "mysql/psi/psi.h" class Diagnostics_area; @@ -42,12 +48,6 @@ typedef const struct charset_info_st CHARSET_INFO; #define PSI_DIGEST_CALL(M) PSI_DYNAMIC_CALL(M) #endif -/** - @defgroup Statement_instrumentation Statement Instrumentation - @ingroup Instrumentation_interface - @{ -*/ - /** @def mysql_statement_register(P1, P2, P3) Statement registration. diff --git a/include/mysql/psi/mysql_table.h b/include/mysql/psi/mysql_table.h index 317627a63ff2c..0d50d7744b046 100644 --- a/include/mysql/psi/mysql_table.h +++ b/include/mysql/psi/mysql_table.h @@ -27,6 +27,10 @@ /** @file mysql/psi/mysql_table.h Instrumentation helpers for table io. + + @defgroup Table_instrumentation Table Instrumentation + @ingroup Instrumentation_interface + @{ */ #include "mysql/psi/psi.h" @@ -35,12 +39,6 @@ #define PSI_TABLE_CALL(M) PSI_DYNAMIC_CALL(M) #endif -/** - @defgroup Table_instrumentation Table Instrumentation - @ingroup Instrumentation_interface - @{ -*/ - #ifdef HAVE_PSI_TABLE_INTERFACE #define MYSQL_UNBIND_TABLE(handler) (handler)->unbind_psi() diff --git a/include/mysql/psi/mysql_thread.h b/include/mysql/psi/mysql_thread.h index 0bc2cd0980efd..bdf25f0d7efc7 100644 --- a/include/mysql/psi/mysql_thread.h +++ b/include/mysql/psi/mysql_thread.h @@ -69,6 +69,12 @@ #endif #endif +/** + @defgroup Thread_instrumentation Thread Instrumentation + @ingroup Instrumentation_interface + @{ +*/ + #ifndef PSI_MUTEX_CALL #define PSI_MUTEX_CALL(M) PSI_DYNAMIC_CALL(M) #endif @@ -85,12 +91,6 @@ #define PSI_THREAD_CALL(M) PSI_DYNAMIC_CALL(M) #endif -/** - @defgroup Thread_instrumentation Thread Instrumentation - @ingroup Instrumentation_interface - @{ -*/ - #ifdef HAVE_PSI_THREAD_INTERFACE #define PSI_CALL_delete_current_thread PSI_THREAD_CALL(delete_current_thread) #define PSI_CALL_get_thread PSI_THREAD_CALL(get_thread) diff --git a/include/mysql/psi/mysql_transaction.h b/include/mysql/psi/mysql_transaction.h index a4444804f5ce4..be267f4e18bb0 100644 --- a/include/mysql/psi/mysql_transaction.h +++ b/include/mysql/psi/mysql_transaction.h @@ -30,16 +30,16 @@ #include "mysql/psi/psi.h" -#ifndef PSI_TRANSACTION_CALL -#define PSI_TRANSACTION_CALL(M) PSI_DYNAMIC_CALL(M) -#endif - /** @defgroup Transaction_instrumentation Transaction Instrumentation @ingroup Instrumentation_interface @{ */ +#ifndef PSI_TRANSACTION_CALL +#define PSI_TRANSACTION_CALL(M) PSI_DYNAMIC_CALL(M) +#endif + #ifdef HAVE_PSI_TRANSACTION_INTERFACE #define MYSQL_START_TRANSACTION(STATE, XID, TRXID, ISO, RO, AC) \ inline_mysql_start_transaction(STATE, XID, TRXID, ISO, RO, AC, __FILE__, __LINE__) diff --git a/include/mysql/psi/psi.h b/include/mysql/psi/psi.h index 10f0937b66ed2..3caf3319c170a 100644 --- a/include/mysql/psi/psi.h +++ b/include/mysql/psi/psi.h @@ -22,6 +22,11 @@ #ifndef MYSQL_PERFORMANCE_SCHEMA_INTERFACE_H #define MYSQL_PERFORMANCE_SCHEMA_INTERFACE_H +/** + @defgroup Instrumentation_interface Instrumentation Interface + @ingroup plugin_api_services_for_plugins + @{ +*/ #ifndef MY_GLOBAL_INCLUDED /* @@ -102,9 +107,6 @@ struct sql_digest_storage; /** @file mysql/psi/psi.h Performance schema instrumentation interface. - - @defgroup Instrumentation_interface Instrumentation Interface - @{ */ /** diff --git a/include/mysql/psi/psi_abi_v0.h b/include/mysql/psi/psi_abi_v0.h index c75a51f7fbfea..cb8210a288d67 100644 --- a/include/mysql/psi/psi_abi_v0.h +++ b/include/mysql/psi/psi_abi_v0.h @@ -26,6 +26,11 @@ This file is only used to automate detection of changes between versions. Do not include this file, include mysql/psi/psi.h instead. */ + +/** + @addtogroup Instrumentation_interface + @{ +*/ #define MY_GLOBAL_INCLUDED #include "mysql/psi/psi.h" - +/** @} */ diff --git a/include/mysql/psi/psi_abi_v1.h b/include/mysql/psi/psi_abi_v1.h index e195ea5ba8d00..258a5e66b839a 100644 --- a/include/mysql/psi/psi_abi_v1.h +++ b/include/mysql/psi/psi_abi_v1.h @@ -26,8 +26,13 @@ This file is only used to automate detection of changes between versions. Do not include this file, include mysql/psi/psi.h instead. */ + +/** + @addtogroup Instrumentation_interface + @{ +*/ #define USE_PSI_1 #define HAVE_PSI_INTERFACE #define MY_GLOBAL_INCLUDED #include "mysql/psi/psi.h" - +/** @} */ diff --git a/include/mysql/psi/psi_abi_v2.h b/include/mysql/psi/psi_abi_v2.h index fdbd36f2259c9..14c4923caa76a 100644 --- a/include/mysql/psi/psi_abi_v2.h +++ b/include/mysql/psi/psi_abi_v2.h @@ -26,8 +26,15 @@ This file is only used to automate detection of changes between versions. Do not include this file, include mysql/psi/psi.h instead. */ + +/** + @addtogroup Instrumentation_interface + @{ +*/ #define USE_PSI_2 #define HAVE_PSI_INTERFACE #define MY_GLOBAL_INCLUDED #include "mysql/psi/psi.h" +/** @} */ + diff --git a/include/mysql/psi/psi_base.h b/include/mysql/psi/psi_base.h index 2963e2e9fa922..387e74fe31e94 100644 --- a/include/mysql/psi/psi_base.h +++ b/include/mysql/psi/psi_base.h @@ -40,7 +40,7 @@ extern "C" { @file mysql/psi/psi_base.h Performance schema instrumentation interface. - @defgroup Instrumentation_interface Instrumentation Interface + @addtogroup Instrumentation_interface @{ */ @@ -167,8 +167,6 @@ extern "C" { #endif /* HAVE_PSI_INTERFACE */ -/** @} */ - /** Instrumented memory key. To instrument memory, a memory key must be obtained using @c register_memory. @@ -176,6 +174,8 @@ extern "C" { */ typedef unsigned int PSI_memory_key; +/** @} */ + #ifdef __cplusplus } #endif diff --git a/include/mysql/psi/psi_memory.h b/include/mysql/psi/psi_memory.h index 5c4320abf61d1..f5845b3857d2b 100644 --- a/include/mysql/psi/psi_memory.h +++ b/include/mysql/psi/psi_memory.h @@ -38,7 +38,7 @@ extern "C" { @file mysql/psi/psi_memory.h Performance schema instrumentation interface. - @defgroup Instrumentation_interface Instrumentation Interface + @addtogroup Instrumentation_interface @{ */ diff --git a/include/mysql/service_base64.h b/include/mysql/service_base64.h index fa54b4923d4fb..c4bb9ae9cde40 100644 --- a/include/mysql/service_base64.h +++ b/include/mysql/service_base64.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_SERVICE_BASE64_INCLUDED /* Copyright (c) 2017, MariaDB This program is free software; you can redistribute it and/or modify @@ -14,6 +13,9 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_SERVICE_BASE64_INCLUDED +#define MYSQL_SERVICE_BASE64_INCLUDED + /** @file my base64 service @@ -21,6 +23,16 @@ Functions for base64 en- and decoding */ +/** + @defgroup plugin_api_service_base64 Base64 service + @ingroup plugin_api_services + + Base64 service + + Functions for base64 en- and decoding. + @{ +*/ + #ifdef __cplusplus extern "C" { #endif @@ -78,5 +90,5 @@ int my_base64_decode(const char *src, size_t src_len, } #endif -#define MYSQL_SERVICE_BASE64_INCLUDED +/** @} */ #endif diff --git a/include/mysql/service_debug_sync.h b/include/mysql/service_debug_sync.h index bdfe79b35ae26..036a02e81c29b 100644 --- a/include/mysql/service_debug_sync.h +++ b/include/mysql/service_debug_sync.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_SERVICE_DEBUG_SYNC_INCLUDED /* Copyright (c) 2009, 2010, Oracle and/or its affiliates. Copyright (c) 2012, Monty Program Ab @@ -17,7 +16,17 @@ /** @file - == Debug Sync Facility == + Debug Sync Facility +*/ + + +#ifndef MYSQL_SERVICE_DEBUG_SYNC_INCLUDED +#define MYSQL_SERVICE_DEBUG_SYNC_INCLUDED + +/** + @defgroup plugin_api_service_debug_sync Debug Sync service + @ingroup plugin_api_services + @brief Debug Sync service The Debug Sync Facility allows placement of synchronization points in the server code by using the DEBUG_SYNC macro: @@ -144,7 +153,7 @@ SET DEBUG_SYNC= 'name TEST'; - === Formal Syntax === + # Formal Syntax The string to "assign" to the DEBUG_SYNC variable can contain: @@ -159,7 +168,7 @@ separated by '&|' must be present or both of them. - === Activation/Deactivation === + # Activation/Deactivation The facility is an optional part of the MySQL server. It is enabled in a debug server by default. @@ -203,7 +212,7 @@ parsed into a debug sync action and stored apart from the variable value. - === Implementation === + # Implementation Pseudo code for a sync point: @@ -219,7 +228,7 @@ new action, the array is sorted again. - === A typical synchronization pattern === + # A typical synchronization pattern There are quite a few places in MySQL, where we use a synchronization pattern like this: @@ -264,7 +273,7 @@ A bit off-topic: At some places, the loop is taken around the whole synchronization pattern: - + @code while (!thd->killed && !end_of_wait_condition) { mysql_mutex_lock(&mutex); @@ -276,7 +285,7 @@ } thd->exit_cond(old_message); } - + @endcode Note that it is important to repeat the test for thd->killed after enter_cond(). Otherwise the killing thread may kill this thread after it tested thd->killed in the loop condition and before it registered @@ -291,31 +300,30 @@ mysql_cond_wait(), the signaling happens at the right place. We have a safe synchronization. - === Co-work with the DBUG facility === + # Co-work with the DBUG facility When running the MySQL test suite with the --debug-dbug command line option, the Debug Sync Facility writes trace messages to the DBUG trace. The following shell commands proved very useful in extracting relevant information: + @code egrep 'query:|debug_sync_exec:' mysql-test/var/log/mysqld.1.trace + @endcode It shows all executed SQL statements and all actions executed by synchronization points. Sometimes it is also useful to see, which synchronization points have been run through (hit) with or without executing actions. Then add - "|debug_sync_point:" to the egrep pattern. - - === Further reading === + `|debug_sync_point:` to the egrep pattern. - For a discussion of other methods to synchronize threads see - http://forge.mysql.com/wiki/MySQL_Internals_Test_Synchronization + # Further reading For complete syntax tests, functional tests, and examples see the test case debug_sync.test. - See also http://forge.mysql.com/worklog/task.php?id=4259 + @{ */ #ifndef MYSQL_ABI_CHECK @@ -361,5 +369,5 @@ extern void (*debug_sync_C_callback_ptr)(MYSQL_THD, const char *, size_t); } #endif -#define MYSQL_SERVICE_DEBUG_SYNC_INCLUDED +/** @} */ #endif diff --git a/include/mysql/service_encryption.h b/include/mysql/service_encryption.h index 8b1d963b4c601..a7aa4a2ab7ad1 100644 --- a/include/mysql/service_encryption.h +++ b/include/mysql/service_encryption.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_SERVICE_ENCRYPTION_INCLUDED /* Copyright (c) 2015, MariaDB This program is free software; you can redistribute it and/or modify @@ -14,14 +13,19 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ -/** - @file - encryption service +#ifndef MYSQL_SERVICE_ENCRYPTION_INCLUDED +#define MYSQL_SERVICE_ENCRYPTION_INCLUDED +/** + @defgroup plugin_api_service_encryption Encryption service + @ingroup plugin_api_services + Functions to support data encryption and encryption key management. + They are normally implemented in an encryption plugin, so this service connects encryption *consumers* (e.g. storage engines) to the encryption *provider* (encryption plugin). + @{ */ #ifndef MYSQL_ABI_CHECK @@ -141,6 +145,6 @@ static inline int encryption_crypt(const unsigned char* src, unsigned int slen, #ifdef __cplusplus } #endif - -#define MYSQL_SERVICE_ENCRYPTION_INCLUDED #endif + +/** @} */ diff --git a/include/mysql/service_encryption_scheme.h b/include/mysql/service_encryption_scheme.h index bcd4d646d9e92..aacc159dce1b1 100644 --- a/include/mysql/service_encryption_scheme.h +++ b/include/mysql/service_encryption_scheme.h @@ -15,10 +15,9 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ /** - @file - encryption scheme service - - A higher-level access to encryption service. + @defgroup plugin_api_service_encryption_scheme Encryption scheme service + @ingroup plugin_api_services + @brief A higher-level access to encryption service. This is a helper service that storage engines use to encrypt tables on disk. It requests keys from the plugin, generates temporary or local keys @@ -65,6 +64,7 @@ any two pages (of the same or different tablespaces) and also that they'll change for the same page when it's modified. They don't need to be secret (they create the IV, not the encryption key). + @{ */ #ifdef __cplusplus @@ -131,3 +131,5 @@ int encryption_scheme_decrypt(const unsigned char* src, unsigned int slen, #define MYSQL_SERVICE_ENCRYPTION_SCHEME_INCLUDED #endif + +/** @} */ diff --git a/include/mysql/service_json.h b/include/mysql/service_json.h index cb748c0c83f29..524aedaa9327c 100644 --- a/include/mysql/service_json.h +++ b/include/mysql/service_json.h @@ -13,34 +13,42 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA */ +/** + @file + json service + +*/ + #ifndef MYSQL_SERVICE_JSON #define MYSQL_SERVICE_JSON /** - @file - json service + @defgroup plugin_api_service_json JSON service + @ingroup plugin_api_services Exports JSON parsing methods for plugins to use. Functions of the service: - json_type - returns the type of the JSON argument, + @ref json_type - returns the type of the JSON argument, and the parsed value if it's scalar (not object or array) - json_get_array_item - expects JSON array as an argument, + @ref json_get_array_item - expects JSON array as an argument, and returns the type of the element at index `n_item`. - Returns JSV_NOTHING type if the array is shorter + Returns @ref JSV_NOTHING type if the array is shorter than n_item and the actual length of the array in value_len. If successful, then `value` up till `value[value_len]` contains the array element at the desired index (n_item). - json_get_object_key - expects JSON object as an argument, + @ref json_get_object_key - expects JSON object as an argument, searches for a key in the object, return it's type and stores its value in `value`. - JSV_NOTHING if no such key found, the number of keys + @ref JSV_NOTHING if no such key found, the number of keys in v_len. - json_get_object_nkey - expects JSON object as an argument. + @ref json_get_object_nkey - expects JSON object as an argument. finds n_key's key in the object, returns it's name, type and value. - JSV_NOTHING if object has less keys than n_key. + @ref JSV_NOTHING if object has less keys than n_key. + + @{ */ @@ -114,6 +122,8 @@ int json_unescape_json(const char *json_str, const char *json_end, } #endif +/** @} */ + #endif /*MYSQL_SERVICE_JSON */ diff --git a/include/mysql/service_kill_statement.h b/include/mysql/service_kill_statement.h index 9f3415a7de5cc..25babd7dc3d33 100644 --- a/include/mysql/service_kill_statement.h +++ b/include/mysql/service_kill_statement.h @@ -20,6 +20,14 @@ @file This service provides functions that allow plugins to support the KILL statement. +*/ + +/** + @defgroup plugin_api_service_kill_statement KILL statement service + @ingroup plugin_api_services + + This service provides functions that allow plugins to support + the KILL statement. In MySQL support for the KILL statement is cooperative. The KILL statement only sets a "killed" flag. This function returns the value @@ -27,12 +35,7 @@ time-consuming loops, and gracefully abort the operation if it is non-zero. - thd_killed(thd) - @return 0 - no KILL statement was issued, continue normally - @return 1 - there was a KILL statement, abort the execution. - - thd_kill_level(thd) - @return thd_kill_levels_enum values + @{ */ #ifdef __cplusplus @@ -49,9 +52,22 @@ extern struct kill_statement_service_st { enum thd_kill_levels (*thd_kill_level_func)(const MYSQL_THD); } *thd_kill_statement_service; -/* backward compatibility helper */ +/** + Backward compatibility helper + + @param THD thread handle + @retval 0 No KILL statement was issued, continue normally + @retval 1 There was a KILL statement, abort the execution. +*/ #define thd_killed(THD) (thd_kill_level(THD) == THD_ABORT_ASAP) + +/** + Check if a KILL statement was issued for the given thread. + + @param THD thread handle + @return @ref thd_kill_levels values +*/ #ifdef MYSQL_DYNAMIC_PLUGIN #define thd_kill_level(THD) \ @@ -67,5 +83,7 @@ enum thd_kill_levels thd_kill_level(const MYSQL_THD); } #endif +/** @} */ + #endif diff --git a/include/mysql/service_log_warnings.h b/include/mysql/service_log_warnings.h index f55df70ef8e01..eebcacb7808e3 100644 --- a/include/mysql/service_log_warnings.h +++ b/include/mysql/service_log_warnings.h @@ -20,9 +20,15 @@ @file This service provides access to the log warning level for the current session. +*/ + +/** + @defgroup plugin_api_service_log_warnings Log Warnings service + @ingroup plugin_api_services + This service provides access to the log warning level for the + current session. - thd_log_warnings(thd) - @return thd->log_warnings + @{ */ #ifdef __cplusplus @@ -33,14 +39,14 @@ extern struct thd_log_warnings_service_st { void *(*thd_log_warnings)(MYSQL_THD); } *thd_log_warnings_service; +/** + Log warnings accessor + @param THD the current session + @return pointer to thd->log_warnings +*/ #ifdef MYSQL_DYNAMIC_PLUGIN # define thd_log_warnings(THD) thd_log_warnings_service->thd_log_warnings(THD) #else -/** - MDL_context accessor - @param thd the current session - @return pointer to thd->mdl_context -*/ int thd_log_warnings(MYSQL_THD thd); #endif @@ -48,5 +54,6 @@ int thd_log_warnings(MYSQL_THD thd); } #endif +/** @} */ #endif diff --git a/include/mysql/service_logger.h b/include/mysql/service_logger.h index 51086b2fcf48d..187e928d46b00 100644 --- a/include/mysql/service_logger.h +++ b/include/mysql/service_logger.h @@ -25,32 +25,40 @@ @file logger service +*/ + +/** + @defgroup plugin_api_service_logger Logger service + @ingroup plugin_api_services Log file with rotation implementation. This service implements logging with possible rotation of the log files. Interface intentionally tries to be similar to FILE* related functions. - So that one can open the log with logger_open(), specifying + So that one can open the log with @ref logger_open(), specifying the limit on the logfile size and the rotations number. Then it's possible to write messages to the log with - logger_printf or logger_vprintf functions. + @ref logger_printf() or @ref logger_vprintf() functions. As the size of the logfile grows over the specified limit, - it is renamed to 'logfile.1'. The former 'logfile.1' becomes - 'logfile.2', etc. The file 'logfile.rotations' is removed. + it is renamed to `logfile.1`. The former `logfile.1` becomes + `logfile.2`, etc. The file `logfile.rotations` is removed. + That's how the rotation works. - The rotation can be forced with the logger_rotate() call. + The rotation can be forced with the @ref logger_rotate() call. - Finally the log should be closed with logger_close(). + Finally the log should be closed with @ref logger_close(). -@note + @note Implementation checks the size of the log file before it starts new printf into it. So the size of the file gets over the limit when it rotates. The access is secured with the mutex, so the log is threadsafe. + + @{ */ @@ -123,5 +131,7 @@ extern struct logger_service_st { } #endif +/** @} */ + #endif /*MYSQL_SERVICE_LOGGER_INCLUDED*/ diff --git a/include/mysql/service_md5.h b/include/mysql/service_md5.h index 336cf70f85ec4..ed398343c2dac 100644 --- a/include/mysql/service_md5.h +++ b/include/mysql/service_md5.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_SERVICE_MD5_INCLUDED /* Copyright (c) 2014, Monty Program Ab This program is free software; you can redistribute it and/or modify @@ -14,11 +13,20 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_SERVICE_MD5_INCLUDED +#define MYSQL_SERVICE_MD5_INCLUDED + /** @file my md5 service +*/ + +/** + @defgroup plugin_api_service_md5 MD5 service + @ingroup plugin_api_services Functions to calculate MD5 hash from a memory buffer + @{ */ #ifdef __cplusplus @@ -64,6 +72,7 @@ void my_md5_result(void *context, unsigned char *digest); } #endif -#define MYSQL_SERVICE_MD5_INCLUDED +/** @} */ + #endif diff --git a/include/mysql/service_my_crypt.h b/include/mysql/service_my_crypt.h index 3a58d0828fc47..022484ff3e423 100644 --- a/include/mysql/service_my_crypt.h +++ b/include/mysql/service_my_crypt.h @@ -22,10 +22,16 @@ @file my crypt service - AES encryption functions, and a function to generate random bytes. +*/ + +/** + @defgroup plugin_api_service_my_crypt My Crypt service + @ingroup plugin_api_services + AES encryption functions, and a function to generate random bytes. - Include my_config.h before this file to use CTR and GCM modes - (they only work if server was compiled with openssl). + Include my_config.h before this file to use CTR and GCM modes + (they only work if server was compiled with openssl). + @{ */ @@ -131,4 +137,6 @@ unsigned int my_aes_ctx_size(enum my_aes_mode mode); } #endif +/** @} */ + #endif /* MYSQL_SERVICE_MY_CRYPT_INCLUDED */ diff --git a/include/mysql/service_my_print_error.h b/include/mysql/service_my_print_error.h index 85a922215e438..2c425c081994f 100644 --- a/include/mysql/service_my_print_error.h +++ b/include/mysql/service_my_print_error.h @@ -19,10 +19,17 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ /** @file include/mysql/service_my_print_error.h +*/ + +/** + @defgroup plugin_api_service_my_print_error My Print Error service + @ingroup plugin_api_services + This service provides functions for plugins to report errors to client (without client, the errors are written to the error log). - + @{ */ + #ifdef __cplusplus extern "C" { #endif @@ -69,5 +76,6 @@ extern void my_printv_error(unsigned int error, const char *format, } #endif +/** @} */ #endif diff --git a/include/mysql/service_my_snprintf.h b/include/mysql/service_my_snprintf.h index c91ea0ab5fd73..6dec6c91124ff 100644 --- a/include/mysql/service_my_snprintf.h +++ b/include/mysql/service_my_snprintf.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_SERVICE_MY_SNPRINTF_INCLUDED /* Copyright (c) 2009, 2012, Oracle and/or its affiliates. All rights reserved. This program is free software; you can redistribute it and/or modify @@ -14,10 +13,17 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_SERVICE_MY_SNPRINTF_INCLUDED +#define MYSQL_SERVICE_MY_SNPRINTF_INCLUDED + /** @file my_snprintf service +*/ +/** + @defgroup plugin_api_service_my_snprintf My Snprintf service + @ingroup plugin_api_services Portable and limited vsnprintf() implementation. This is a portable, limited vsnprintf() implementation, with some @@ -28,12 +34,33 @@ it). "Limited" means that it does not support all the C89 features. But it supports few extensions, not in any standard. - my_vsnprintf(to, n, fmt, ap) + @{ +*/ + +#ifdef __cplusplus +extern "C" { +#endif + +#ifndef MYSQL_ABI_CHECK +#include +#include +#endif +#include + +extern struct my_snprintf_service_st { + size_t (*my_snprintf_type)(char*, size_t, const char*, ...) + ATTRIBUTE_FORMAT_FPTR(printf, 3, 4); + size_t (*my_vsnprintf_type)(char *, size_t, const char*, va_list) + ATTRIBUTE_FORMAT_FPTR(printf, 3, 0); +} *my_snprintf_service; + + +/** + A portable, limited vsnprintf() implementation, with some extra features. @param[out] to A buffer to store the result in @param[in] n Store up to n-1 characters, followed by an end 0 @param[in] fmt printf-like format string - @param[in] ap Arguments @return a number of bytes written to a buffer *excluding* terminating '\0' @@ -42,71 +69,56 @@ @verbatim %[][][.][][] @endverbatim - where everything but the \ is optional. + where everything but the `format` is optional. - Two one-character \ are recognized: - '0' has the standard zero-padding semantics; - '-' is parsed, but silently ignored; + Two one-character `flags` are recognized: + - '0' has the standard zero-padding semantics; + - '-' is parsed, but silently ignored; - Both \ and \ are the same as in the standard. + Both `length` and `precision` are the same as in the standard. They can be specified as integers, or as '*' to consume an int argument. - \ can be 'l', 'll', or 'z'. + `size modifier` can be 'l', 'll', or 'z'. - Supported \s are 's' (null pointer is accepted, printed as "(null)"), - 'c', 'd', 'i', 'u', 'x', 'X', 'o', 'p' (works as "0x%x"), 'f', and 'g'. + Supported `format`s are `s` (null pointer is accepted, printed as "(null)"), + `c`, `d`, `i`, `u`, `x`, `X`, `o`, `p` (works as "0x%x"), `f`, and `g`. - The '$n' syntax for positional arguments is supported. + The `$n` syntax for positional arguments is supported. Format extensions: - Format 'sQ' - quotes the string with '`' (backtick)s similar to "`%s`", - but also "escapes" existing '`'s in the string to '\`\`' as in SQL ''''. - Format 'sB' + - Format 'sQ' + quotes the string with "\`" (backtick)s similar to "%s", + but also "escapes" existing backticks in the string to '\\\`\\\`' as in SQL ''''. + - Format 'sB' treats the argument as a byte sequence. It reads and prints exactly - \ bytes without terminating on any '\0's in the sequence. - The default \ when it's unspecified is not defined. + `precision` bytes without terminating on any `\0`s in the sequence. + The default `precision` when it's unspecified is not defined. - Format 'sT' + - Format 'sT' replaces the end of the printed string with "..." if it was truncated. - Format 'sS' + - Format 'sS' is a synonym for 's'. It's an escape that avoid consuming the following plain char as one of the above extension suffixes. Example: "Data Class: %sSType" - Format 'iE' + - Format 'iE' treats the argument as an errno number. It prints this number, a space, then its corresponding error message in double quotes. In other words: + @code printf("%iE", n) === printf("%i \"%sT\"", n, strerror(n)) - Format 'dE' has no effect. Therefore, to escape '%iE', use '%dE' instead. + @endcode + - Format 'dE' has no effect. Therefore, to escape '%iE', use '%dE' instead. - Unrecognized and multiple suffixes are not parsed; - for example, both "%sTQ" and "%iQ" will suffix with a literal 'Q'. + Unrecognized and multiple suffixes are not parsed; + for example, both "%sTQ" and "%iQ" will suffix with a literal 'Q'. */ -#ifdef __cplusplus -extern "C" { -#endif - -#ifndef MYSQL_ABI_CHECK -#include -#include -#endif -#include - -extern struct my_snprintf_service_st { - size_t (*my_snprintf_type)(char*, size_t, const char*, ...) - ATTRIBUTE_FORMAT_FPTR(printf, 3, 4); - size_t (*my_vsnprintf_type)(char *, size_t, const char*, va_list) - ATTRIBUTE_FORMAT_FPTR(printf, 3, 0); -} *my_snprintf_service; - #ifdef MYSQL_DYNAMIC_PLUGIN -#define my_vsnprintf my_snprintf_service->my_vsnprintf_type -#define my_snprintf my_snprintf_service->my_snprintf_type +#define my_snprintf(to, n, fmt, ...) my_snprintf_service->my_snprintf_type(to, n, fmt, __VA_ARGS__) +#define my_vsnprintf(to, n, fmt, ap) my_snprintf_service->my_vsnprintf_type(to, n, fmt, ap) #else @@ -121,5 +133,6 @@ size_t my_vsnprintf(char *to, size_t n, const char* fmt, va_list ap) } #endif -#define MYSQL_SERVICE_MY_SNPRINTF_INCLUDED +/** @} */ + #endif diff --git a/include/mysql/service_print_check_msg.h b/include/mysql/service_print_check_msg.h index c2c7cf0a3814e..794549f951f56 100644 --- a/include/mysql/service_print_check_msg.h +++ b/include/mysql/service_print_check_msg.h @@ -20,21 +20,28 @@ This service provides functions to write messages for check or repair */ +/** + @defgroup plugin_api_service_print_check_msg Print Check Msg service + @ingroup plugin_api_services + + This service provides functions to write messages for check or repair + @{ +*/ #ifdef __cplusplus extern "C" { #endif - extern struct print_check_msg_service_st { - void (*print_check_msg)(MYSQL_THD, const char *db_name, const char *table_name, + void (*print_check_msg)(MYSQL_THD thd, const char *db_name, const char *table_name, const char *op, const char *msg_type, const char *message, my_bool print_to_log); } *print_check_msg_service; #ifdef MYSQL_DYNAMIC_PLUGIN -# define print_check_msg_context(_THD) print_check_msg_service->print_check_msg +# define print_check_msg(thd, db_name, table_name, op, msg_type, message, print_to_log) \ + print_check_msg_service->print_check_msg(thd, db_name, table_name, op, msg_type, message, print_to_log) #else -extern void print_check_msg(MYSQL_THD, const char *db_name, const char *table_name, +extern void print_check_msg(MYSQL_THD thd, const char *db_name, const char *table_name, const char *op, const char *msg_type, const char *message, my_bool print_to_log); #endif @@ -42,3 +49,5 @@ extern void print_check_msg(MYSQL_THD, const char *db_name, const char *table_na #ifdef __cplusplus } #endif + +/** @} */ diff --git a/include/mysql/service_progress_report.h b/include/mysql/service_progress_report.h index 2e7dc7d0d97e1..b054e532c9add 100644 --- a/include/mysql/service_progress_report.h +++ b/include/mysql/service_progress_report.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_SERVICE_PROGRESS_REPORT_INCLUDED /* Copyright (C) 2011 Monty Program Ab This program is free software; you can redistribute it and/or modify @@ -14,15 +13,28 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_SERVICE_PROGRESS_REPORT_INCLUDED +#define MYSQL_SERVICE_PROGRESS_REPORT_INCLUDED + /** @file This service allows plugins to report progress of long running operations - to the server. The progress report is visible in SHOW PROCESSLIST, + to the server. +*/ + +/** + @defgroup plugin_api_service_progress_report Progress Report service + @ingroup plugin_api_services + Allows plugins to report progress of long running operations to the server. + + The progress report is visible in SHOW PROCESSLIST, INFORMATION_SCHEMA.PROCESSLIST, and is sent to the client if requested. The functions are documented at https://mariadb.com/docs/server/reference/product-development/mariadb-internals/using-mariadb-with-your-programs-api + + @{ */ #ifdef __cplusplus @@ -77,6 +89,6 @@ const char *set_thd_proc_info(MYSQL_THD, const char * info, const char *func, } #endif -#define MYSQL_SERVICE_PROGRESS_REPORT_INCLUDED +/** @} */ #endif diff --git a/include/mysql/service_sha1.h b/include/mysql/service_sha1.h index d864e23fa849d..dd9542c17e2b8 100644 --- a/include/mysql/service_sha1.h +++ b/include/mysql/service_sha1.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_SERVICE_SHA1_INCLUDED /* Copyright (c) 2013, 2014, Monty Program Ab This program is free software; you can redistribute it and/or modify @@ -14,11 +13,21 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_SERVICE_SHA1_INCLUDED +#define MYSQL_SERVICE_SHA1_INCLUDED + /** @file my sha1 service +*/ + +/** + @defgroup plugin_api_service_sha1 SHA1 service + @ingroup plugin_api_services + my sha1 service Functions to calculate SHA1 hash from a memory buffer + @{ */ #ifdef __cplusplus @@ -42,12 +51,12 @@ extern struct my_sha1_service_st { #ifdef MYSQL_DYNAMIC_PLUGIN -#define my_sha1(A,B,C) my_sha1_service->my_sha1_type(A,B,C) -#define my_sha1_multi my_sha1_service->my_sha1_multi_type +#define my_sha1(digest, buf, len) my_sha1_service->my_sha1_type(digest, buf, len) +#define my_sha1_multi(digest, ...) my_sha1_service->my_sha1_multi_type(digest, __VA_ARGS__) #define my_sha1_context_size() my_sha1_service->my_sha1_context_size_type() -#define my_sha1_init(A) my_sha1_service->my_sha1_init_type(A) -#define my_sha1_input(A,B,C) my_sha1_service->my_sha1_input_type(A,B,C) -#define my_sha1_result(A,B) my_sha1_service->my_sha1_result_type(A,B) +#define my_sha1_init(context) my_sha1_service->my_sha1_init_type(context) +#define my_sha1_input(context, buf, len) my_sha1_service->my_sha1_input_type(context, buf, len) +#define my_sha1_result(context, digest) my_sha1_service->my_sha1_result_type(context, digest) #else @@ -64,6 +73,5 @@ void my_sha1_result(void *context, unsigned char *digest); } #endif -#define MYSQL_SERVICE_SHA1_INCLUDED +/** @} */ #endif - diff --git a/include/mysql/service_sha2.h b/include/mysql/service_sha2.h index 00834a9b8f432..bbf6084cda1b6 100644 --- a/include/mysql/service_sha2.h +++ b/include/mysql/service_sha2.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_SERVICE_SHA2_INCLUDED /* Copyright (c) 2017, MariaDB This program is free software; you can redistribute it and/or modify @@ -14,6 +13,9 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_SERVICE_SHA2_INCLUDED +#define MYSQL_SERVICE_SHA2_INCLUDED + /** @file my sha2 service @@ -21,6 +23,15 @@ Functions to calculate SHA2 hash from a memory buffer */ +/** + @defgroup plugin_api_service_sha2 SHA2 service + @ingroup plugin_api_services + my sha2 service + + Functions to calculate SHA2 hash from a memory buffer + @{ +*/ + #ifdef __cplusplus extern "C" { #endif @@ -61,33 +72,33 @@ extern struct my_sha2_service_st { #ifdef MYSQL_DYNAMIC_PLUGIN -#define my_sha224(A,B,C) my_sha2_service->my_sha224_type(A,B,C) -#define my_sha224_multi my_sha2_service->my_sha224_multi_type +#define my_sha224(digest, buf, len) my_sha2_service->my_sha224_type(digest, buf, len) +#define my_sha224_multi(digest, ...) my_sha2_service->my_sha224_multi_type(digest, __VA_ARGS__) #define my_sha224_context_size() my_sha2_service->my_sha224_context_size_type() -#define my_sha224_init(A) my_sha2_service->my_sha224_init_type(A) -#define my_sha224_input(A,B,C) my_sha2_service->my_sha224_input_type(A,B,C) -#define my_sha224_result(A,B) my_sha2_service->my_sha224_result_type(A,B) +#define my_sha224_init(context) my_sha2_service->my_sha224_init_type(context) +#define my_sha224_input(context, buf, len) my_sha2_service->my_sha224_input_type(context, buf, len) +#define my_sha224_result(context, digest) my_sha2_service->my_sha224_result_type(context, digest) -#define my_sha256(A,B,C) my_sha2_service->my_sha256_type(A,B,C) -#define my_sha256_multi my_sha2_service->my_sha256_multi_type +#define my_sha256(digest, buf, len) my_sha2_service->my_sha256_type(digest, buf, len) +#define my_sha256_multi(digest, ...) my_sha2_service->my_sha256_multi_type(digest, __VA_ARGS__) #define my_sha256_context_size() my_sha2_service->my_sha256_context_size_type() -#define my_sha256_init(A) my_sha2_service->my_sha256_init_type(A) -#define my_sha256_input(A,B,C) my_sha2_service->my_sha256_input_type(A,B,C) -#define my_sha256_result(A,B) my_sha2_service->my_sha256_result_type(A,B) +#define my_sha256_init(context) my_sha2_service->my_sha256_init_type(context) +#define my_sha256_input(context, buf, len) my_sha2_service->my_sha256_input_type(context, buf, len) +#define my_sha256_result(context, digest) my_sha2_service->my_sha256_result_type(context, digest) -#define my_sha384(A,B,C) my_sha2_service->my_sha384_type(A,B,C) -#define my_sha384_multi my_sha2_service->my_sha384_multi_type +#define my_sha384(digest, buf, len) my_sha2_service->my_sha384_type(digest, buf, len) +#define my_sha384_multi(digest, ...) my_sha2_service->my_sha384_multi_type(digest, __VA_ARGS__) #define my_sha384_context_size() my_sha2_service->my_sha384_context_size_type() -#define my_sha384_init(A) my_sha2_service->my_sha384_init_type(A) -#define my_sha384_input(A,B,C) my_sha2_service->my_sha384_input_type(A,B,C) -#define my_sha384_result(A,B) my_sha2_service->my_sha384_result_type(A,B) +#define my_sha384_init(context) my_sha2_service->my_sha384_init_type(context) +#define my_sha384_input(context, buf, len) my_sha2_service->my_sha384_input_type(context, buf, len) +#define my_sha384_result(context, digest) my_sha2_service->my_sha384_result_type(context, digest) -#define my_sha512(A,B,C) my_sha2_service->my_sha512_type(A,B,C) -#define my_sha512_multi my_sha2_service->my_sha512_multi_type +#define my_sha512(digest, buf, len) my_sha2_service->my_sha512_type(digest, buf, len) +#define my_sha512_multi(digest, ...) my_sha2_service->my_sha512_multi_type(digest, __VA_ARGS__) #define my_sha512_context_size() my_sha2_service->my_sha512_context_size_type() -#define my_sha512_init(A) my_sha2_service->my_sha512_init_type(A) -#define my_sha512_input(A,B,C) my_sha2_service->my_sha512_input_type(A,B,C) -#define my_sha512_result(A,B) my_sha2_service->my_sha512_result_type(A,B) +#define my_sha512_init(context) my_sha2_service->my_sha512_init_type(context) +#define my_sha512_input(context, buf, len) my_sha2_service->my_sha512_input_type(context, buf, len) +#define my_sha512_result(context, digest) my_sha2_service->my_sha512_result_type(context, digest) #else @@ -125,6 +136,7 @@ void my_sha512_result(void *context, unsigned char *digest); } #endif -#define MYSQL_SERVICE_SHA2_INCLUDED +/** @} */ + #endif diff --git a/include/mysql/service_sql.h b/include/mysql/service_sql.h index a4a61cc0f47df..cc54833619cac 100644 --- a/include/mysql/service_sql.h +++ b/include/mysql/service_sql.h @@ -23,22 +23,31 @@ /** @file SQL service +*/ + +/** + @defgroup plugin_api_service_sql SQL service + @ingroup plugin_api_services + SQL service Interface for plugins to execute SQL queries on the local server. - Functions of the service are the 'server-limited' client library: - mysql_init - mysql_real_connect_local - mysql_real_connect - mysql_errno - mysql_error - mysql_real_query - mysql_affected_rows - mysql_num_rows - mysql_store_result - mysql_free_result - mysql_fetch_row - mysql_close + Functions of the service are the 'server-limited' client library: + + - @ref mysql_init + - @ref mysql_real_connect_local + - @ref mysql_real_connect + - @ref mysql_errno + - @ref mysql_error + - @ref mysql_real_query + - @ref mysql_affected_rows + - @ref mysql_num_rows + - @ref mysql_store_result + - @ref mysql_free_result + - @ref mysql_fetch_row + - @ref mysql_close + + @{ */ @@ -78,27 +87,28 @@ extern struct sql_service_st { #ifdef MYSQL_DYNAMIC_PLUGIN -#define mysql_init(M) sql_service->mysql_init_func(M) -#define mysql_real_connect_local(M) sql_service->mysql_real_connect_local_func(M) -#define mysql_real_connect(M,H,U,PW,D,P,S,F) sql_service->mysql_real_connect_func(M,H,U,PW,D,P,S,F) -#define mysql_errno(M) sql_service->mysql_errno_func(M) -#define mysql_error(M) sql_service->mysql_error_func(M) +#define mysql_init(mysql) sql_service->mysql_init_func(mysql) +#define mysql_real_connect_local(mysql) sql_service->mysql_real_connect_local_func(mysql) +#define mysql_real_connect(mysql,host,user,password,db,port,socket,flags) \ + sql_service->mysql_real_connect_func(mysql,host,user,password,db,port,socket,flags) +#define mysql_errno(mysql) sql_service->mysql_errno_func(mysql) +#define mysql_error(mysql) sql_service->mysql_error_func(mysql) #define mysql_real_query sql_service->mysql_real_query_func -#define mysql_affected_rows(M) sql_service->mysql_affected_rows_func(M) -#define mysql_num_rows(R) sql_service->mysql_num_rows_func(R) -#define mysql_store_result(M) sql_service->mysql_store_result_func(M) -#define mysql_free_result(R) sql_service->mysql_free_result_func(R) -#define mysql_fetch_row(R) sql_service->mysql_fetch_row_func(R) -#define mysql_close(M) sql_service->mysql_close_func(M) -#define mysql_options(M,O,V) sql_service->mysql_options_func(M,O,V) -#define mysql_fetch_lengths(R) sql_service->mysql_fetch_lengths_func(R) -#define mysql_set_character_set(M,C) sql_service->mysql_set_character_set_func(M,C) -#define mysql_num_fields(R) sql_service->mysql_num_fields_func(R) -#define mysql_select_db(M,D) sql_service->mysql_select_db_func(M,D) -#define mysql_use_result(M) sql_service->mysql_use_result_func(M) -#define mysql_fetch_fields(R) sql_service->mysql_fetch_fields_func(R) -#define mysql_real_escape_string(M,T,F,L) sql_service->mysql_real_escape_string_func(M,T,F,L) -#define mysql_ssl_set(M,K,C1,C2,C3,C4) sql_service->mysql_ssl_set_func(M,K,C1,C2,C3,C4) +#define mysql_affected_rows(mysql) sql_service->mysql_affected_rows_func(mysql) +#define mysql_num_rows(result) sql_service->mysql_num_rows_func(result) +#define mysql_store_result(mysql) sql_service->mysql_store_result_func(mysql) +#define mysql_free_result(result) sql_service->mysql_free_result_func(result) +#define mysql_fetch_row(result) sql_service->mysql_fetch_row_func(result) +#define mysql_close(mysql) sql_service->mysql_close_func(mysql) +#define mysql_options(mysql,option,arg) sql_service->mysql_options_func(mysql,option,arg) +#define mysql_fetch_lengths(result) sql_service->mysql_fetch_lengths_func(result) +#define mysql_set_character_set(mysql,cs_name) sql_service->mysql_set_character_set_func(mysql,cs_name) +#define mysql_num_fields(result) sql_service->mysql_num_fields_func(result) +#define mysql_select_db(mysql,db) sql_service->mysql_select_db_func(mysql,db) +#define mysql_use_result(mysql) sql_service->mysql_use_result_func(mysql) +#define mysql_fetch_fields(result) sql_service->mysql_fetch_fields_func(result) +#define mysql_real_escape_string(mysql,to,from,length) sql_service->mysql_real_escape_string_func(mysql,to,from,length) +#define mysql_ssl_set(mysql,key,cert,ca,capath,cipher) sql_service->mysql_ssl_set_func(mysql,key,cert,ca,capath,cipher) #else @@ -120,4 +130,6 @@ MYSQL *mysql_real_connect_local(MYSQL *mysql); } #endif +/** @} */ + #endif /*MYSQL_SERVICE_SQL */ diff --git a/include/mysql/service_thd.h b/include/mysql/service_thd.h index 5be9cb8b81ed3..64f01273e360c 100644 --- a/include/mysql/service_thd.h +++ b/include/mysql/service_thd.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_SERVICE_THD_INCLUDED /* Copyright (c) 2026, MariaDB Corporation. This program is free software; you can redistribute it and/or modify @@ -14,12 +13,26 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_SERVICE_THD_INCLUDED +#define MYSQL_SERVICE_THD_INCLUDED + /** @file include/mysql/service_thd.h This service provides functions for plugins and storage engines to access current thd. */ +/** + @defgroup plugin_api_service_thd THD service + @ingroup plugin_api_services + Access to the current thd + + This service provides functions for plugins and storage engines to access + current thd. + + @{ +*/ + #ifdef __cplusplus extern "C" { #endif @@ -28,13 +41,13 @@ extern struct thd_service_st { MYSQL_THD (*get_current_thd)(void); } *thd_service; -#ifdef MYSQL_DYNAMIC_PLUGIN -# define get_current_thd() thd_service->get_current_thd() -#else /** - current thd accessor + Current session (thd) accessor @return pointer to current thd */ +#ifdef MYSQL_DYNAMIC_PLUGIN +# define get_current_thd() thd_service->get_current_thd() +#else MYSQL_THD get_current_thd(); #endif @@ -42,5 +55,6 @@ MYSQL_THD get_current_thd(); } #endif -#define MYSQL_SERVICE_THD_INCLUDED +/** @} */ + #endif diff --git a/include/mysql/service_thd_alloc.h b/include/mysql/service_thd_alloc.h index 014277b5d0012..4f666ed7ee21a 100644 --- a/include/mysql/service_thd_alloc.h +++ b/include/mysql/service_thd_alloc.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_SERVICE_THD_ALLOC_INCLUDED /* Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved. This program is free software; you can redistribute it and/or modify @@ -14,10 +13,23 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_SERVICE_THD_ALLOC_INCLUDED +#define MYSQL_SERVICE_THD_ALLOC_INCLUDED + /** @file This service provides functions to allocate memory in a connection local - memory pool. The memory allocated there will be automatically freed at the + memory pool. + +*/ +/** + @defgroup plugin_api_service_thd_alloc THD alloc service + @ingroup plugin_api_services + + This service provides functions to allocate memory in a connection local + memory pool + + The memory allocated there will be automatically freed at the end of the statement, don't use it for allocations that should live longer than that. For short living allocations this is more efficient than using my_malloc and friends, and automatic "garbage collection" allows not @@ -25,6 +37,7 @@ The pool is best for small to medium objects, don't use it for large allocations - they are better served with my_malloc. + @{ */ #ifndef MYSQL_ABI_CHECK @@ -69,24 +82,6 @@ extern struct thd_alloc_service_st { #ifdef MYSQL_DYNAMIC_PLUGIN -#define thd_alloc(thd,size) (thd_alloc_service->thd_alloc_func((thd), (size))) - -#define thd_calloc(thd,size) (thd_alloc_service->thd_calloc_func((thd), (size))) - -#define thd_strdup(thd,str) (thd_alloc_service->thd_strdup_func((thd), (str))) - -#define thd_strmake(thd,str,size) \ - (thd_alloc_service->thd_strmake_func((thd), (str), (size))) - -#define thd_memdup(thd,str,size) \ - (thd_alloc_service->thd_memdup_func((thd), (str), (size))) - -#define thd_make_lex_string(thd, lex_str, str, size, allocate_lex_string) \ - (thd_alloc_service->thd_make_lex_string_func((thd), (lex_str), (str), \ - (size), (allocate_lex_string))) - -#else - /** Allocate memory in the connection's local memory pool @@ -96,27 +91,26 @@ extern struct thd_alloc_service_st { large chunks of memory. Use for temporary storage only. The memory will be freed automatically at the end of the statement; no explicit code is required to prevent memory leaks. - - @see alloc_root() */ -void *thd_alloc(const MYSQL_THD thd, size_t size); +#define thd_alloc(thd,size) (thd_alloc_service->thd_alloc_func((thd), (size))) /** - @see thd_alloc() + @see @ref thd_alloc() */ -void *thd_calloc(const MYSQL_THD thd, size_t size); +#define thd_calloc(thd,size) (thd_alloc_service->thd_calloc_func((thd), (size))) /** @see thd_alloc() */ -char *thd_strdup(const MYSQL_THD thd, const char *str); +#define thd_strdup(thd,str) (thd_alloc_service->thd_strdup_func((thd), (str))) /** @see thd_alloc() */ -char *thd_strmake(const MYSQL_THD thd, const char *str, size_t size); +#define thd_strmake(thd,str,size) \ + (thd_alloc_service->thd_strmake_func((thd), (str), (size))) /** @see thd_alloc() */ -void *thd_memdup(const MYSQL_THD thd, const void* str, size_t size); - +#define thd_memdup(thd,str,size) \ + (thd_alloc_service->thd_memdup_func((thd), (str), (size))) /** Create a LEX_STRING in this connection's local memory pool @@ -130,17 +124,27 @@ void *thd_memdup(const MYSQL_THD thd, const void* str, size_t size); @see thd_alloc() */ +#define thd_make_lex_string(thd, lex_str, str, size, allocate_lex_string) \ + (thd_alloc_service->thd_make_lex_string_func((thd), (lex_str), (str), \ + (size), (allocate_lex_string))) + +#else + +void *thd_alloc(const MYSQL_THD thd, size_t size); +void *thd_calloc(const MYSQL_THD thd, size_t size); +char *thd_strdup(const MYSQL_THD thd, const char *str); +char *thd_strmake(const MYSQL_THD thd, const char *str, size_t size); +void *thd_memdup(const MYSQL_THD thd, const void* str, size_t size); MYSQL_CONST_LEX_STRING *thd_make_lex_string(const MYSQL_THD thd, MYSQL_CONST_LEX_STRING *lex_str, const char *str, size_t size, int allocate_lex_string); - #endif #ifdef __cplusplus } #endif -#define MYSQL_SERVICE_THD_ALLOC_INCLUDED +/** @} */ #endif diff --git a/include/mysql/service_thd_autoinc.h b/include/mysql/service_thd_autoinc.h index 4e881d7262ffe..b3b5dbafb1e18 100644 --- a/include/mysql/service_thd_autoinc.h +++ b/include/mysql/service_thd_autoinc.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_SERVICE_THD_AUTOINC_INCLUDED /* Copyright (C) 2013 MariaDB Foundation. This program is free software; you can redistribute it and/or modify @@ -14,6 +13,9 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_SERVICE_THD_AUTOINC_INCLUDED +#define MYSQL_SERVICE_THD_AUTOINC_INCLUDED + /** @file This service provides access to the auto_increment related system variables: @@ -21,7 +23,19 @@ @@auto_increment_offset @@auto_increment_increment */ +/** + @defgroup plugin_api_service_thd_autoinc THD autoinc service + @ingroup plugin_api_services + Access to the auto_increment related system variables. + + This service is used by plugins that need to know the current values of the auto_increment_offset and auto_increment_increment system variables for a given thread. + This service provides access to the auto_increment related system variables: + + - `@@auto_increment_offset` + - `@@auto_increment_increment` + @{ +*/ #ifdef __cplusplus extern "C" { #endif @@ -31,16 +45,16 @@ extern struct thd_autoinc_service_st { unsigned long* off, unsigned long* inc); } *thd_autoinc_service; -#ifdef MYSQL_DYNAMIC_PLUGIN -#define thd_get_autoinc(thd, off, inc) \ - (thd_autoinc_service->thd_get_autoinc_func((thd), (off), (inc))) -#else /** Return autoincrement system variables @param[in] thd user thread connection handle @param[out] off the value of @@SESSION.auto_increment_offset @param[out] inc the value of @@SESSION.auto_increment_increment */ +#ifdef MYSQL_DYNAMIC_PLUGIN +#define thd_get_autoinc(thd, off, inc) \ + (thd_autoinc_service->thd_get_autoinc_func((thd), (off), (inc))) +#else void thd_get_autoinc(const MYSQL_THD thd, unsigned long* off, unsigned long* inc); #endif @@ -49,5 +63,5 @@ void thd_get_autoinc(const MYSQL_THD thd, } #endif -#define MYSQL_SERVICE_THD_AUTOINC_INCLUDED +/** @} */ #endif diff --git a/include/mysql/service_thd_error_context.h b/include/mysql/service_thd_error_context.h index 0b9082dd314cb..843378f97180d 100644 --- a/include/mysql/service_thd_error_context.h +++ b/include/mysql/service_thd_error_context.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_SERVICE_THD_STMT_DA_INCLUDED /* Copyright (C) 2013 MariaDB Foundation. This program is free software; you can redistribute it and/or modify @@ -14,6 +13,9 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_SERVICE_THD_ERROR_CONTEXT_INCLUDED +#define MYSQL_SERVICE_THD_ERROR_CONTEXT_INCLUDED + /** @file This service provides access to the statement diagnostics area: @@ -21,7 +23,17 @@ - error number - row for warning (e.g. for multi-row INSERT statements) */ +/** + @defgroup plugin_api_service_thd_error_context THD error context service + @ingroup plugin_api_services + Error context service to access the statement diagnostics area. + This service provides access to the statement diagnostics area: + - error message + - error number + - row for warning (e.g. for multi-row INSERT statements) + @{ + */ #ifdef __cplusplus extern "C" { #endif @@ -39,47 +51,47 @@ extern struct thd_error_context_service_st { } *thd_error_context_service; #ifdef MYSQL_DYNAMIC_PLUGIN -#define thd_get_error_message(thd) \ - (thd_error_context_service->thd_get_error_message_func((thd))) -#define thd_get_error_number(thd) \ - (thd_error_context_service->thd_get_error_number_func((thd))) -#define thd_get_error_row(thd) \ - (thd_error_context_service->thd_get_error_row_func((thd))) -#define thd_inc_error_row(thd) \ - (thd_error_context_service->thd_inc_error_row_func((thd))) -#define thd_get_error_context_description(thd, buffer, length, max_query_len) \ - (thd_error_context_service->thd_get_error_context_description_func((thd), \ - (buffer), \ - (length), \ - (max_query_len))) -#else /** Return error message @param thd user thread connection handle @return error text */ -const char *thd_get_error_message(const MYSQL_THD thd); +#define thd_get_error_message(thd) \ + (thd_error_context_service->thd_get_error_message_func((thd))) /** Return error number @param thd user thread connection handle @return error number */ -unsigned int thd_get_error_number(const MYSQL_THD thd); +#define thd_get_error_number(thd) \ + (thd_error_context_service->thd_get_error_number_func((thd))) /** Return the current row number (i.e. in a multiple INSERT statement) @param thd user thread connection handle @return row number */ -unsigned long thd_get_error_row(const MYSQL_THD thd); +#define thd_get_error_row(thd) \ + (thd_error_context_service->thd_get_error_row_func((thd))) /** Increment the current row number @param thd user thread connection handle */ -void thd_inc_error_row(MYSQL_THD thd); +#define thd_inc_error_row(thd) \ + (thd_error_context_service->thd_inc_error_row_func((thd))) /** Return a text description of a thread, its security context (user,host) and the current query. */ +#define thd_get_error_context_description(thd, buffer, length, max_query_length) \ + (thd_error_context_service->thd_get_error_context_description_func((thd), \ + (buffer), \ + (length), \ + (max_query_length))) +#else +const char *thd_get_error_message(const MYSQL_THD thd); +unsigned int thd_get_error_number(const MYSQL_THD thd); +unsigned long thd_get_error_row(const MYSQL_THD thd); +void thd_inc_error_row(MYSQL_THD thd); char *thd_get_error_context_description(MYSQL_THD thd, char *buffer, unsigned int length, unsigned int max_query_length); @@ -89,5 +101,6 @@ char *thd_get_error_context_description(MYSQL_THD thd, } #endif -#define MYSQL_SERVICE_THD_STMT_DA_INCLUDED -#endif +/** @} */ + +#endif /* MYSQL_SERVICE_THD_ERROR_CONTEXT_INCLUDED */ diff --git a/include/mysql/service_thd_mdl.h b/include/mysql/service_thd_mdl.h index 19b0476914ed7..d0b379a3ac7e2 100644 --- a/include/mysql/service_thd_mdl.h +++ b/include/mysql/service_thd_mdl.h @@ -21,6 +21,16 @@ metadata locks. */ +/** + @defgroup plugin_api_service_thd_mdl THD MDL service + @ingroup plugin_api_services + Access to the metadata locks. + + This service provides functions for plugins and storage engines to access + metadata locks. + @{ +*/ + #ifdef __cplusplus extern "C" { #endif @@ -30,17 +40,19 @@ extern struct thd_mdl_service_st { void *(*thd_mdl_context)(MYSQL_THD); } *thd_mdl_service; -#ifdef MYSQL_DYNAMIC_PLUGIN -# define thd_mdl_context(_THD) thd_mdl_service->thd_mdl_context(_THD) -#else /** MDL_context accessor @param thd the current session @return pointer to thd->mdl_context */ +#ifdef MYSQL_DYNAMIC_PLUGIN +# define thd_mdl_context(thd) thd_mdl_service->thd_mdl_context(thd) +#else void *thd_mdl_context(MYSQL_THD thd); #endif #ifdef __cplusplus } #endif + +/** @} */ diff --git a/include/mysql/service_thd_rnd.h b/include/mysql/service_thd_rnd.h index 6d5f65227888e..248b18930d5ac 100644 --- a/include/mysql/service_thd_rnd.h +++ b/include/mysql/service_thd_rnd.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_SERVICE_THD_RND_INCLUDED /* Copyright (C) 2017 MariaDB Corporation This program is free software; you can redistribute it and/or modify @@ -14,6 +13,9 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_SERVICE_THD_RND_INCLUDED +#define MYSQL_SERVICE_THD_RND_INCLUDED + /** @file This service provides access to the thd-local random number generator. @@ -23,6 +25,16 @@ to the shared rnd state. */ +/** + @defgroup plugin_api_service_thd_rnd THD RND service + @ingroup plugin_api_services + Access to the thd-local random number generator. + + It's preferable over the global one, because concurrent threads + can generate random numbers without fighting each other over the access + to the shared rnd state. + @{ +*/ #ifdef __cplusplus extern "C" { #endif @@ -37,12 +49,7 @@ extern struct thd_rnd_service_st { } *thd_rnd_service; #ifdef MYSQL_DYNAMIC_PLUGIN -#define thd_rnd(A) thd_rnd_service->thd_rnd_ptr(A) -#define thd_create_random_password(A,B,C) thd_rnd_service->thd_c_r_p_ptr(A,B,C) -#else - -double thd_rnd(MYSQL_THD thd); - +#define thd_rnd(thd) thd_rnd_service->thd_rnd_ptr(thd) /** Generate string of printable random characters of requested length. @@ -51,13 +58,16 @@ double thd_rnd(MYSQL_THD thd); long; result string is always null-terminated @param[in] length How many random characters to put in buffer */ +#define thd_create_random_password(thd,to,length) thd_rnd_service->thd_c_r_p_ptr(thd,to,length) +#else +double thd_rnd(MYSQL_THD thd); void thd_create_random_password(MYSQL_THD thd, char *to, size_t length); - #endif #ifdef __cplusplus } #endif -#define MYSQL_SERVICE_THD_RND_INCLUDED +/** @} */ + #endif diff --git a/include/mysql/service_thd_specifics.h b/include/mysql/service_thd_specifics.h index a4078bd5cc038..f27c0a11db7b7 100644 --- a/include/mysql/service_thd_specifics.h +++ b/include/mysql/service_thd_specifics.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_SERVICE_THD_SPECIFICS_INCLUDED /* Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved. This program is free software; you can redistribute it and/or modify @@ -14,43 +13,56 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_SERVICE_THD_SPECIFICS_INCLUDED +#define MYSQL_SERVICE_THD_SPECIFICS_INCLUDED + /** @file THD specific for plugin(s) - This API provides pthread_getspecific like functionality to plugin authors. - This is a functional alternative to the declarative MYSQL_THDVAR +*/ + +/** + @defgroup plugin_api_service_thd_specifics THD Specifics service + @ingroup plugin_api_services + THD specific for plugin(s) + + This API provides pthread_getspecific() like functionality to plugin authors. + This is a functional alternative to the declarative MYSQL_THDVAR_* API. - A plugin should at init call thd_key_create that create a key that + A plugin should at init call @ref thd_key_create() that create a key that will have storage in each THD. The key should be used by all threads and can be used concurrently from all threads. - A plugin should at deinit call thd_key_delete. + A plugin should at deinit call @ref thd_key_delete(). - Alternatively, a plugin can use thd_key_create_from_var(K,V) to create - a key that corresponds to a named MYSQL_THDVAR variable. + Alternatively, a plugin can use @ref thd_key_create_from_var(K,V) to create + a key that corresponds to a named MYSQL_THDVAR_* variable. This API is also safe when using pool-of-threads in which case - pthread_getspecific is not, because the actual OS thread may change. + pthread_getspecific() is not, because the actual OS thread may change. @note - Normally one should prefer MYSQL_THDVAR declarative API. + Normally one should prefer MYSQL_THDVAR_* declarative API. The benefits are: - It supports typed variables (int, char*, enum, etc), not only void*. - - The memory allocated for MYSQL_THDVAR is free'd automatically - (if PLUGIN_VAR_MEMALLOC is specified). + - The memory allocated for MYSQL_THDVAR_* is free'd automatically + (if @ref PLUGIN_VAR_MEMALLOC is specified). - Continuous loading and unloading of the same plugin does not allocate memory for same variables over and over again. - An example of using MYSQL_THDVAR for a thd local storage: - + An example of using MYSQL_THDVAR_* for a thd local storage: + @code MYSQL_THDVAR_STR(my_tls, PLUGIN_VAR_MEMALLOC | PLUGIN_VAR_NOSYSVAR | PLUGIN_VAR_NOCMDOPT, "thd local storage example", 0, 0, 0); + @endcode + + @{ */ #ifdef __cplusplus @@ -70,32 +82,37 @@ extern struct thd_specifics_service_st { #ifdef MYSQL_DYNAMIC_PLUGIN -#define thd_key_create(K) (thd_specifics_service->thd_key_create_func(K)) -#define thd_key_delete(K) (thd_specifics_service->thd_key_delete_func(K)) -#define thd_getspecific(T, K) (thd_specifics_service->thd_getspecific_func(T, K)) -#define thd_setspecific(T, K, V) (thd_specifics_service->thd_setspecific_func(T, K, V)) - -#else - /** * create THD specific storage * @return 0 on success * else errno is returned */ -int thd_key_create(MYSQL_THD_KEY_T *key); - +#define thd_key_create(key) (thd_specifics_service->thd_key_create_func(key)) /** * delete THD specific storage */ -void thd_key_delete(MYSQL_THD_KEY_T *key); - +#define thd_key_delete(key) (thd_specifics_service->thd_key_delete_func(key)) +/** + * get thd specific storage + * - first time this is called from a thread it will return 0 + * - this call is thread-safe in that different threads may call this + * simultaneously if operating on different THDs. + * - this call acquires no mutexes and is implemented as an array lookup + */ +#define thd_getspecific(thd, key) (thd_specifics_service->thd_getspecific_func(thd, key)) /** - * get/set thd specific storage + * set thd specific storage * - first time this is called from a thread it will return 0 * - this call is thread-safe in that different threads may call this * simultaneously if operating on different THDs. * - this call acquires no mutexes and is implemented as an array lookup */ +#define thd_setspecific(thd, key, value) (thd_specifics_service->thd_setspecific_func(thd, key, value)) + +#else + +int thd_key_create(MYSQL_THD_KEY_T *key); +void thd_key_delete(MYSQL_THD_KEY_T *key); void* thd_getspecific(MYSQL_THD thd, MYSQL_THD_KEY_T key); int thd_setspecific(MYSQL_THD thd, MYSQL_THD_KEY_T key, void *value); @@ -105,6 +122,7 @@ int thd_setspecific(MYSQL_THD thd, MYSQL_THD_KEY_T key, void *value); } #endif -#define MYSQL_SERVICE_THD_SPECIFICS_INCLUDED +/** @} */ + #endif diff --git a/include/mysql/service_thd_timezone.h b/include/mysql/service_thd_timezone.h index f3f2867f3261b..6a7cae5ba9284 100644 --- a/include/mysql/service_thd_timezone.h +++ b/include/mysql/service_thd_timezone.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_SERVICE_THD_TIMEZONE_INCLUDED /* Copyright (C) 2013 MariaDB Foundation. This program is free software; you can redistribute it and/or modify @@ -14,20 +13,32 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_SERVICE_THD_TIMEZONE_INCLUDED +#define MYSQL_SERVICE_THD_TIMEZONE_INCLUDED + /** @file + THD timezone handling for plugin(s) +*/ + +/** + @defgroup plugin_api_service_thd_timezone THD Timezone service + @ingroup plugin_api_services + THD timezone handling for plugin(s) + This service provides functions to convert between my_time_t and - MYSQL_TIME taking into account the current value of the time_zone + MYSQL_TIME taking into account the current value of the `time_zone` session variable. The values of the my_time_t type are in Unix timestamp format, - i.e. the number of seconds since "1970-01-01 00:00:00 UTC". + i.e. the number of seconds since `1970-01-01 00:00:00 UTC`. The values of the MYSQL_TIME type are in the current time zone, - according to thd->variables.time_zone. + according to `thd->variables.time_zone`. - If the MYSQL_THD parameter is NULL, then global_system_variables.time_zone + If the @ref MYSQL_THD parameter is NULL, then `global_system_variables.time_zone` is used for conversion. + @{ */ #ifndef MYSQL_ABI_CHECK @@ -74,5 +85,6 @@ void thd_TIME_to_str(MYSQL_THD thd, const MYSQL_TIME *ltime, const char *format, } #endif -#define MYSQL_SERVICE_THD_TIMEZONE_INCLUDED +/** @} */ + #endif diff --git a/include/mysql/service_thd_wait.h b/include/mysql/service_thd_wait.h index c20878fd85b24..05df08f1c5fc9 100644 --- a/include/mysql/service_thd_wait.h +++ b/include/mysql/service_thd_wait.h @@ -20,37 +20,20 @@ @file include/mysql/service_thd_wait.h This service provides functions for plugins and storage engines to report when they are going to sleep/stall. - - SYNOPSIS - thd_wait_begin() - call just before a wait begins - thd Thread object - Use NULL if the thd is NOT known. - wait_type Type of wait - 1 -- short wait (e.g. for mutex) - 2 -- medium wait (e.g. for disk io) - 3 -- large wait (e.g. for locked row/table) - NOTES - This is used by the threadpool to have better knowledge of which - threads that currently are actively running on CPUs. When a thread - reports that it's going to sleep/stall, the threadpool scheduler is - free to start another thread in the pool most likely. The expected wait - time is simply an indication of how long the wait is expected to - become, the real wait time could be very different. - - thd_wait_end() called immediately after the wait is complete - - thd_wait_end() MUST be called if thd_wait_begin() was called. - - Using thd_wait_...() service is optional but recommended. Using it will - improve performance as the thread pool will be more active at managing the - thread workload. */ -#ifdef __cplusplus -extern "C" { -#endif +/** + @defgroup plugin_api_service_thd_wait THD Wait service + @ingroup plugin_api_services + + This service provides functions for plugins and storage engines to report + when they are going to sleep/stall. + + + Using @ref thd_wait_begin() / @ref thd_wait_end() service is optional + but recommended. Using it will improve performance as the thread pool + will be more active at managing the thread workload. -/* One should only report wait events that could potentially block for a long time. A mutex wait is too short of an event to report. The reason is that an event which is reported leads to a new thread starts @@ -62,11 +45,18 @@ extern "C" { that could easily be for many milliseconds or even seconds and the same holds true for global read locks, table locks and other meta data locks. Another event of interest is going to sleep for an extended time. + + @{ */ + +#ifdef __cplusplus +extern "C" { +#endif + typedef enum _thd_wait_type_e { - THD_WAIT_SLEEP= 1, - THD_WAIT_DISKIO= 2, - THD_WAIT_ROW_LOCK= 3, + THD_WAIT_SLEEP= 1, /**< Short wait (e.g. for mutex) */ + THD_WAIT_DISKIO= 2, /**< Medium wait (e.g. for disk io) */ + THD_WAIT_ROW_LOCK= 3, /**< Large wait (e.g. for locked row/table) */ THD_WAIT_GLOBAL_LOCK= 4, THD_WAIT_META_DATA_LOCK= 5, THD_WAIT_TABLE_LOCK= 6, @@ -85,20 +75,34 @@ extern struct thd_wait_service_st { #ifdef MYSQL_DYNAMIC_PLUGIN -#define thd_wait_begin(_THD, _WAIT_TYPE) \ - thd_wait_service->thd_wait_begin_func(_THD, _WAIT_TYPE) -#define thd_wait_end(_THD) thd_wait_service->thd_wait_end_func(_THD) - +/** + Call just before a wait begins + @param thd Thread object. Use NULL if the thd is NOT known. + @param wait_type Type of wait: one of @ref thd_wait_type + + This is used by the threadpool to have better knowledge of which + threads that currently are actively running on CPUs. When a thread + reports that it's going to sleep/stall, the threadpool scheduler is + free to start another thread in the pool most likely. The expected wait + time is simply an indication of how long the wait is expected to + become, the real wait time could be very different. + */ +#define thd_wait_begin(thd, wait_type) \ + thd_wait_service->thd_wait_begin_func(thd, wait_type) +/** + Call just after a wait ends + @param thd Thread object. Use NULL if the thd is NOT known. +*/ +#define thd_wait_end(thd) thd_wait_service->thd_wait_end_func(thd) #else - void thd_wait_begin(MYSQL_THD thd, int wait_type); void thd_wait_end(MYSQL_THD thd); - #endif #ifdef __cplusplus } #endif +/** @} */ #endif diff --git a/include/mysql/service_wsrep.h b/include/mysql/service_wsrep.h index 8c001ca147063..1f2b8021d7e5a 100644 --- a/include/mysql/service_wsrep.h +++ b/include/mysql/service_wsrep.h @@ -1,23 +1,3 @@ -#ifndef MYSQL_SERVICE_WSREP_INCLUDED -#define MYSQL_SERVICE_WSREP_INCLUDED - -enum Wsrep_service_key_type -{ - WSREP_SERVICE_KEY_SHARED, - WSREP_SERVICE_KEY_REFERENCE, - WSREP_SERVICE_KEY_UPDATE, - WSREP_SERVICE_KEY_EXCLUSIVE -}; - - -/* the bits in the bitmask for disabling temporarily some asserts */ -#define WSREP_ASSERT_INNODB_TRX 1 - - -#if (defined (MYSQL_DYNAMIC_PLUGIN) && defined(MYSQL_SERVICE_WSREP_DYNAMIC_INCLUDED)) || (!defined(MYSQL_DYNAMIC_PLUGIN) && defined(MYSQL_SERVICE_WSREP_STATIC_INCLUDED)) - -#else - /* Copyright (c) 2015, 2020, MariaDB Corporation Ab 2018 Codership Oy @@ -34,6 +14,9 @@ enum Wsrep_service_key_type along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_SERVICE_WSREP_INCLUDED +#define MYSQL_SERVICE_WSREP_INCLUDED + /** @file wsrep service @@ -41,6 +24,30 @@ enum Wsrep_service_key_type Interface to WSREP functionality in the server. For engines that want to support galera. */ + +/** + @defgroup plugin_api_service_wsrep WSREP service + @ingroup plugin_api_services + Access to WSREP functionality + + @{ +*/ + +enum Wsrep_service_key_type +{ + WSREP_SERVICE_KEY_SHARED, + WSREP_SERVICE_KEY_REFERENCE, + WSREP_SERVICE_KEY_UPDATE, + WSREP_SERVICE_KEY_EXCLUSIVE +}; + + +/** The bits in the bitmask for disabling temporarily some asserts */ +#define WSREP_ASSERT_INNODB_TRX 1 +#if (defined (MYSQL_DYNAMIC_PLUGIN) && defined(MYSQL_SERVICE_WSREP_DYNAMIC_INCLUDED)) || (!defined(MYSQL_DYNAMIC_PLUGIN) && defined(MYSQL_SERVICE_WSREP_STATIC_INCLUDED)) + +#else + #include #ifdef __cplusplus #endif @@ -49,10 +56,8 @@ struct xid_t; struct wsrep_ws_handle; struct wsrep_buf; -/* Must match to definition in sql/mysqld.h */ +/** Must match to definition in sql/mysqld.h */ typedef int64 query_id_t; - - extern struct wsrep_service_st { my_bool (*get_wsrep_recovery_func)(); bool (*wsrep_consistency_check_func)(MYSQL_THD thd); @@ -104,55 +109,76 @@ extern struct wsrep_service_st { uint32 (*wsrep_get_domain_id_func)(); } *wsrep_service; -#define MYSQL_SERVICE_WSREP_INCLUDED #endif #ifdef MYSQL_DYNAMIC_PLUGIN #define MYSQL_SERVICE_WSREP_DYNAMIC_INCLUDED #define get_wsrep_recovery() wsrep_service->get_wsrep_recovery_func() -#define wsrep_consistency_check(T) wsrep_service->wsrep_consistency_check_func(T) -#define wsrep_is_wsrep_xid(X) wsrep_service->wsrep_is_wsrep_xid_func(X) -#define wsrep_xid_seqno(X) wsrep_service->wsrep_xid_seqno_func(X) -#define wsrep_xid_uuid(X) wsrep_service->wsrep_xid_uuid_func(X) +#define wsrep_consistency_check(thd) wsrep_service->wsrep_consistency_check_func(thd) +#define wsrep_is_wsrep_xid(xid) wsrep_service->wsrep_is_wsrep_xid_func(xid) +#define wsrep_xid_seqno(xid) wsrep_service->wsrep_xid_seqno_func(xid) +#define wsrep_xid_uuid(xid) wsrep_service->wsrep_xid_uuid_func(xid) +/** + Return true if wsrep is enabled for a thd. This means that + wsrep is enabled globally and the thd has wsrep on +*/ #define wsrep_on(thd) (thd) && WSREP_ON && wsrep_service->wsrep_on_func(thd) #define wsrep_prepare_key_for_innodb(A,B,C,D,E,F,G) wsrep_service->wsrep_prepare_key_for_innodb_func(A,B,C,D,E,F,G) -#define wsrep_thd_LOCK(T) wsrep_service->wsrep_thd_LOCK_func(T) -#define wsrep_thd_TRYLOCK(T) wsrep_service->wsrep_thd_TRYLOCK_func(T) -#define wsrep_thd_UNLOCK(T) wsrep_service->wsrep_thd_UNLOCK_func(T) -#define wsrep_thd_kill_LOCK(T) wsrep_service->wsrep_thd_kill_LOCK_func(T) -#define wsrep_thd_kill_UNLOCK(T) wsrep_service->wsrep_thd_kill_UNLOCK_func(T) -#define wsrep_thd_query(T) wsrep_service->wsrep_thd_query_func(T) -#define wsrep_thd_retry_counter(T) wsrep_service->wsrep_thd_retry_counter_func(T) -#define wsrep_thd_ignore_table(T) wsrep_service->wsrep_thd_ignore_table_func(T) -#define wsrep_thd_trx_seqno(T) wsrep_service->wsrep_thd_trx_seqno_func(T) +/** Lock thd wsrep lock */ +#define wsrep_thd_LOCK(thd) wsrep_service->wsrep_thd_LOCK_func(thd) +/** + Try thd wsrep lock. + @return non-zero if lock could not be taken. +*/ +#define wsrep_thd_TRYLOCK(thd) wsrep_service->wsrep_thd_TRYLOCK_func(thd) +/** Unlock thd wsrep lock */ +#define wsrep_thd_UNLOCK(thd) wsrep_service->wsrep_thd_UNLOCK_func(thd) +#define wsrep_thd_kill_LOCK(thd) wsrep_service->wsrep_thd_kill_LOCK_func(thd) +#define wsrep_thd_kill_UNLOCK(thd) wsrep_service->wsrep_thd_kill_UNLOCK_func(thd) +#define wsrep_thd_query(thd) wsrep_service->wsrep_thd_query_func(thd) +#define wsrep_thd_retry_counter(thd) wsrep_service->wsrep_thd_retry_counter_func(thd) +#define wsrep_thd_ignore_table(thd) wsrep_service->wsrep_thd_ignore_table_func(thd) +#define wsrep_thd_trx_seqno(thd) wsrep_service->wsrep_thd_trx_seqno_func(thd) #define wsrep_set_data_home_dir(A) wsrep_service->wsrep_set_data_home_dir_func(A) -#define wsrep_thd_is_BF(T,S) wsrep_service->wsrep_thd_is_BF_func(T,S) -#define wsrep_thd_is_aborting(T) wsrep_service->wsrep_thd_is_aborting_func(T) -#define wsrep_thd_in_rollback_func(T) wsrep_service->wsrep_thd_in_rollback_func(T) -#define wsrep_thd_is_local(T) wsrep_service->wsrep_thd_is_local_func(T) -#define wsrep_thd_self_abort(T) wsrep_service->wsrep_thd_self_abort_func(T) -#define wsrep_thd_append_key(T,W,N,K) wsrep_service->wsrep_thd_append_key_func(T,W,N,K) -#define wsrep_thd_append_table_key(T,D,B,K) wsrep_service->wsrep_thd_append_table_key_func(T,D,B,K) -#define wsrep_thd_is_local_transaction(T) wsrep_service->wsrep_thd_is_local_transaction_func(T) -#define wsrep_thd_client_state_str(T) wsrep_service->wsrep_thd_client_state_str_func(T) -#define wsrep_thd_client_mode_str(T) wsrep_service->wsrep_thd_client_mode_str_func(T) -#define wsrep_thd_transaction_state_str(T) wsrep_service->wsrep_thd_transaction_state_str_func(T) -#define wsrep_thd_transaction_id(T) wsrep_service->wsrep_thd_transaction_id_func(T) -#define wsrep_thd_bf_abort(T,T2,S) wsrep_service->wsrep_thd_bf_abort_func(T,T2,S) -#define wsrep_thd_order_before(L,R) wsrep_service->wsrep_thd_order_before_func(L,R) -#define wsrep_handle_SR_rollback(B,V) wsrep_service->wsrep_handle_SR_rollback_func(B,V) -#define wsrep_thd_skip_locking(T) wsrep_service->wsrep_thd_skip_locking_func(T) +/** @retval true if thd is in BF mode, either high_priority or TOI */ +#define wsrep_thd_is_BF(thd,sync) wsrep_service->wsrep_thd_is_BF_func(thd,sync) +#define wsrep_thd_is_aborting(thd) wsrep_service->wsrep_thd_is_aborting_func(thd) +/** @retval true if thd is in rollback */ +#define wsrep_thd_in_rollback_func(thd) wsrep_service->wsrep_thd_in_rollback_func(thd) +/** @retval true if thd is in replicating mode */ +#define wsrep_thd_is_local(thd) wsrep_service->wsrep_thd_is_local_func(thd) +#define wsrep_thd_self_abort(thd) wsrep_service->wsrep_thd_self_abort_func(thd) +#define wsrep_thd_append_key(thd,key,nkeys,key_type) wsrep_service->wsrep_thd_append_key_func(thd,key,nkeys,key_type) +#define wsrep_thd_append_table_key(thd,db,table,key) wsrep_service->wsrep_thd_append_table_key_func(thd,db,table,key) +#define wsrep_thd_is_local_transaction(thd) wsrep_service->wsrep_thd_is_local_transaction_func(thd) +/** @return thd client state string */ +#define wsrep_thd_client_state_str(thd) wsrep_service->wsrep_thd_client_state_str_func(thd) +/** @return thd client mode string */ +#define wsrep_thd_client_mode_str(thd) wsrep_service->wsrep_thd_client_mode_str_func(thd) +/** @return thd transaction state string */ +#define wsrep_thd_transaction_state_str(thd) wsrep_service->wsrep_thd_transaction_state_str_func(thd) +/** @return current transaction id */ +#define wsrep_thd_transaction_id(thd) wsrep_service->wsrep_thd_transaction_id_func(thd) +/** Mark thd own transaction as aborted */ +#define wsrep_thd_bf_abort(bf_thd,victim_thd,signal) wsrep_service->wsrep_thd_bf_abort_func(bf_thd,victim_thd,signal) +#define wsrep_thd_order_before(left,right) wsrep_service->wsrep_thd_order_before_func(left,right) +#define wsrep_handle_SR_rollback(BF_thd,victim_thd) wsrep_service->wsrep_handle_SR_rollback_func(BF_thd,victim_thd) +#define wsrep_thd_skip_locking(thd) wsrep_service->wsrep_thd_skip_locking_func(thd) #define wsrep_get_sr_table_name() wsrep_service->wsrep_get_sr_table_name_func() #define wsrep_get_debug() wsrep_service->wsrep_get_debug_func() -#define wsrep_commit_ordered(T) wsrep_service->wsrep_commit_ordered_func(T) -#define wsrep_thd_is_applying(T) wsrep_service->wsrep_thd_is_applying_func(T) -#define wsrep_OSU_method_get(T) wsrep_service->wsrep_OSU_method_get_func(T) -#define wsrep_thd_has_ignored_error(T) wsrep_service->wsrep_thd_has_ignored_error_func(T) -#define wsrep_thd_set_ignored_error(T,V) wsrep_service->wsrep_thd_set_ignored_error_func(T,V) -#define wsrep_report_bf_lock_wait(T,I) wsrep_service->wsrep_report_bf_lock_wait(T,I) -#define wsrep_thd_set_PA_unsafe(T) wsrep_service->wsrep_thd_set_PA_unsafe_func(T) -#define wsrep_get_domain_id(T) wsrep_service->wsrep_get_domain_id_func(T) +#define wsrep_commit_ordered(thd) wsrep_service->wsrep_commit_ordered_func(thd) +/** + @return true if thd is in high priority mode + @todo: rename to is_high_priority() + */ +#define wsrep_thd_is_applying(thd) wsrep_service->wsrep_thd_is_applying_func(thd) +#define wsrep_OSU_method_get(thd) wsrep_service->wsrep_OSU_method_get_func(thd) +#define wsrep_thd_has_ignored_error(thd) wsrep_service->wsrep_thd_has_ignored_error_func(thd) +#define wsrep_thd_set_ignored_error(thd,val) wsrep_service->wsrep_thd_set_ignored_error_func(thd,val) +#define wsrep_report_bf_lock_wait(thd,trx_id) wsrep_service->wsrep_report_bf_lock_wait(thd,trx_id) +#define wsrep_thd_set_PA_unsafe(thd) wsrep_service->wsrep_thd_set_PA_unsafe_func(thd) +#define wsrep_get_domain_id(thd) wsrep_service->wsrep_get_domain_id_func(thd) #else #define MYSQL_SERVICE_WSREP_STATIC_INCLUDED @@ -266,4 +292,6 @@ extern "C" void wsrep_report_bf_lock_wait(const THD *thd, extern "C" void wsrep_thd_set_PA_unsafe(MYSQL_THD thd); extern "C" uint32 wsrep_get_domain_id(); #endif + +/** @} */ #endif /* MYSQL_SERVICE_WSREP_INCLUDED */ diff --git a/include/mysql/services.h b/include/mysql/services.h index c5607d424b2ba..dee8c55a454a0 100644 --- a/include/mysql/services.h +++ b/include/mysql/services.h @@ -1,4 +1,3 @@ -#ifndef MYSQL_SERVICES_INCLUDED /* Copyright (c) 2009, 2010, Oracle and/or its affiliates. Copyright (c) 2012, 2017, MariaDB @@ -15,10 +14,21 @@ along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ +#ifndef MYSQL_SERVICES_INCLUDED +#define MYSQL_SERVICES_INCLUDED + #ifdef __cplusplus extern "C" { #endif +/** + @defgroup plugin_api_services Plugin Services + @ingroup plugin_api_services_for_plugins + + A set of services provided by the server to plugins. + @sa @ref impl_server_plugin_services +*/ + #include #include #include @@ -48,6 +58,5 @@ extern "C" { } #endif -#define MYSQL_SERVICES_INCLUDED #endif