vsql_allow_preview_extensions = ON が設定されている場合にのみインストールできます。プレビュー層の有効化と機能の登録方法については、プレビュー機能を参照してください。
ステータス変数
status_var 機能(vsql::status_var)は、拡張機能が MySQL ステータス変数として long long および double カウンターを公開できるようにします。拡張機能はストレージを所有し、値を書き込みます。サーバーはステータス変数がクエリされるたびにポインタ経由で読み取ります。
vsql::preview_status_var::make_capability() で機能を構築し、make_int(name, value_ptr) または make_double(name, value_ptr) から得られる記述子のブレースリストを渡します。テンプレートはブレースリストからカウントを推測するため、明示的なサイズは必要ありません。
完全な例
make_int には long long * が必要です。make_double には double * が必要です。これらがサポートされる唯一の2つの型です。
SQL からのアクセス
INSTALL EXTENSION my_ext 後、変数は拡張機能名をプレフィックスとして表示されます:
++ で同時にインクリメントする場合、まれに値が失われる可能性がありますが、SHOW STATUS で公開される近似カウンターとしては許容されます。
システム変数
sys_var 機能(vsql::sys_var)は、拡張機能所有のストレージに紐付けられた MySQL システム変数を登録できるようにします。4つの型がサポートされます: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>() をチェーンします。コールバックは var_name() および型付きアクセサ(as_int()、as_str()、および as_enum())を備えた sv::SysVarChange を受け取ります。
サーバーは、グローバルなシステム変数ロックを保持したままそのコールバックを呼び出します。その中でこの拡張機能の別の変数をストレージポインタ経由で読み書きすることは安全です。また、サーバーが同じロックの下でそれらの変数を読み取るため、他のセッションはすぐに新しい値を参照できます。
機能オブジェクトは静的ストレージ持続期間でなければなりません。MySQL はユーザーが変数を設定する際にストレージポインタに直接書き込みます。
enum 変数は名前(
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 はすべての接続で共有される1つの値を持ちますが、session_var は各接続に SET SESSION で設定する独自の値を与えます。新しいセッションの開始点は、記述子のデフォルト、または SET GLOBAL で最後に格納された値です。変数のスコープは登録時に固定されます — セッションごとの変数にはこの機能を、グローバルな変数には vsql::sys_var を使用してください。
サポートされる型は2つだけです: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 は空文字列のデフォルトで始まります。機能オブジェクトは、このページの他のすべてのプレビュー機能と同様に、静的ストレージ持続期間が必要です。
セッション値の読み取り
読み取りパスは2つあり、どちらも呼び出し元の接続のスレッドに対して解決されます — そのため、どちらも接続スレッド上(接続上で実行される VDF またはコールバック)で呼び出さなければならず、バックグラウンドのスレッドワーカーから呼び出してはいけません:SESSION_VARS.get_session_int(name, out)/get_session_str(name, out)— 名前をキーとし、呼び出しのたびに変数を再解決します。たまに読み取る場合にはこれを使用してください。またSTR変数にとってはこれが唯一のパスです。STRスロットは別途割り当てられたバッファへのポインタを保持しており、同時に実行されるSET SESSIONやUNINSTALLがそれを解放しうるため、ロックフリーの文字列用高速パスはありません。SESSION_VARS.int_var(name)は、最初のread()で自身を遅延解決して結果をキャッシュするIntVarを返すため、機能がロードされる前にファイル/静的スコープで宣言できます。それ以降の各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 を使用しない場合、拡張機能がインストールされたままの再起動後には、各変数はコンパイル時のデフォルトで再び現れます。