vsql_allow_preview_extensions = ON 才能安装。有关如何启用预览层和注册功能,请参阅预览功能。
状态变量
status_var 功能 (vsql::status_var) 允许扩展程序将 long long 和 double 计数器作为 MySQL 状态变量公开。扩展程序拥有存储空间并写入其中;服务器每次查询状态变量时,都会通过指针读取。
使用 vsql::preview_status_var::make_capability() 构建功能,并传递来自 make_int(name, value_ptr) 或 make_double(name, value_ptr) 的大括号列表。模板从大括号列表中推断计数,因此不需要显式大小。
完整示例
make_int 需要一个 long long *;make_double 需要一个 double *。仅支持这两种类型。
从 SQL 访问
在INSTALL EXTENSION my_ext 之后,该变量将以扩展程序名称作为前缀显示:
++)可能会偶尔丢失;这对于通过 SHOW STATUS 公开的近似调用计数器是可以接受的。
系统变量
sys_var 功能 (vsql::sys_var) 允许扩展程序注册由扩展程序拥有的存储空间支持的 MySQL 系统变量。支持四种类型:BOOL (bool *)、INT (long long *)、STR (char **),以及 ENUM (unsigned long *,存储一个从零开始的索引,指向一个固定且有序的名称列表)。INT 描述符还携带 min_val 和 max_val 边界;所有描述符都携带默认值和注释。
使用 vsql::preview_sys_var::make_capability() 和相应的工厂函数 make_bool、make_int、make_str 和 make_enum 构建功能。功能对象还公开 get() 和 set(),以便从扩展程序代码中进行编程访问。两者都返回 false 表示成功。
要响应值更改,请在描述符上链接 .on_change<&fn>()。回调将接收一个 sv::SysVarChange,其中包含 var_name() 和类型化的访问器 (as_int()、as_str() 和 as_enum())。
服务器在持有其全局系统变量锁的同时调用该回调。在那里通过存储指针读取或写入本扩展程序的另一个变量是安全的,并且其他会话会立即看到新值,因为服务器也在同一把锁下读取这些变量。
功能对象必须具有静态存储期。当用户设置变量时,MySQL 会直接写入存储指针。
枚举变量可以按名称设置 (
SET GLOBAL my_ext.mode = 'sync'),也可以按该名称从零开始的索引设置;无论哪种方式,服务器都会在接受该值之前根据 names 对其进行验证,拒绝无法识别的名称或超出范围的索引,而不是存储它:
make_str:值空间是封闭的,并在 SET 时强制执行。一个便捷重载可以从 static const char *const NAMES[] = {...} 数组推断 name_count,因此可以省略计数参数。
完整示例
从 SQL 访问
安装INSTALL EXTENSION my_ext 后,可以使用扩展名作为组件前缀来访问变量:
从扩展代码读取和写入
对于 INT 和 BOOL 变量,直接读取全局存储指针——MySQL 以原子方式更新这些变量。要通过 MySQL 更新变量(以便服务器处理锁定、范围验证和持久性),请调用SYS_VARS.set(extension_name, var_name, scope, value)。set 和 get 都成功时返回 false。两者都不能从 on_change 回调中调用:它们都会在系统变量锁上死锁。
set 和 get 以 const char * 接收扩展名和变量名。INT 变量只能用整数值设置;用字符串值调用 set 会失败并返回 true(针对 INT 变量)。BOOL、STRING、DOUBLE 和 ENUM 变量请用字符串值设置。
scope 参数控制持久性:
会话变量
session_var 功能 (vsql::session_var) 允许扩展程序注册按会话(THD 本地)的系统变量——在功能上等同于插件的 MYSQL_THDVAR_*。它是 vsql::sys_var 的会话作用域同类:sys_var 只有一个由每个连接共享的值,而 session_var 为每个连接提供各自的值,通过 SET SESSION 设置。新会话的起始值是描述符的默认值,或者 SET GLOBAL 最后存储的值。变量的作用域在注册时固定——按会话的变量使用此功能,全局变量使用 vsql::sys_var。
仅支持两种类型:INT (long long) 和 STR (std::string)。没有 BOOL 或 DOUBLE 会话变量,也没有 on_change 回调机制——与 vsql::sys_var 不同,扩展程序只能通过读回会话变量的值来观察它,而不会在它更改时收到通知。
声明功能
使用vsql::preview_session_var::make_capability() 构建功能,并传递来自 make_int(name, comment) 或 make_str(name, comment) 的大括号描述符列表,每个描述符都通过流式的 .default_()、.min() 和 .max() 设置器进行配置(min/max 仅适用于 INT):
make_int 起初不受约束(默认值 0,完整的 long long 范围);make_str 起初以空字符串为默认值。功能对象需要静态存储期,与本页上的其他每一个预览功能相同。
读取会话值
有两条读取路径,两者都针对调用方连接的线程进行解析——因此两者都必须在连接线程上调用(在该连接上运行的 VDF 或回调),绝不能从后台线程工作器调用:SESSION_VARS.get_session_int(name, out)/get_session_str(name, out)——按名称键控,每次调用都重新解析变量。请将其用于偶尔的读取;对于STR变量,它是唯一的路径:没有无锁的字符串快速路径,因为STR槽位持有一个指向单独分配的缓冲区的指针,而并发的SET SESSION或UNINSTALL可能会释放该缓冲区。SESSION_VARS.int_var(name)返回一个IntVar,它在首次read()时惰性地解析自身并缓存结果,因此可以在功能加载之前于文件/静态作用域声明它。之后的每次read()都是一次无锁的按线程偏移量加载——没有名称查找,没有全局锁——等同于插件的THDVAR(thd, var)。此快速路径仅适用于INT。
从 SQL 访问
在INSTALL EXTENSION my_ext 之后,每个变量都以扩展程序名称作为组件前缀,并且可以同时通过 @@session. 和 @@global. 读取/设置:
SET SESSION 影响,并且在设置自己的值之前会看到编译时的默认值;SET GLOBAL 更改的是新会话或重置后的会话所采用的默认值,而不是任何会话已经设置的值。
超出范围的 INT 赋值会被截断到边界并发出警告,类型错误的赋值会被拒绝,与普通的 MySQL 系统变量完全相同:
重启行为
SET PERSIST 和 SET PERSIST_ONLY 对会话变量的全局值的作用与对任何 MySQL 系统变量相同:该值在服务器重启后仍然存在,并且每个新会话都从它开始。SET SESSION 的值是按连接的状态,不会在重启后保留。如果没有 SET PERSIST,在扩展程序仍然安装的情况下重启后,每个变量都会重新回到其编译时的默认值。