vsql_allow_preview_extensions = ON が設定されている場合にのみインストールできます。プレビュー層の有効化と機能の登録方法については、プレビュー機能を参照してください。
スレッドワーカー
thread worker 機能(vsql::preview::thread_worker)は、サーバーによって駆動されるバックグラウンドスレッドを拡張機能が実行できるようにします。スレッドは、サーバーが拡張機能ロード時に登録する制御システム変数を介して開始および停止されます。サーバーは、定期タイマー、ファイルディスクリプタの準備完了(レディ状態)、有効/無効イベントに応じて拡張機能の作業関数を呼び出します。
機能名 VEF_PREVIEW_THREAD_WORKER_NAME は "vsql::preview::thread_worker" です。
機能の宣言
ヘッダーを含め、ファイルスコープで作業関数をインスタンス化したThreadWorkerCapability を宣言し、.with() に渡します:
ThreadWorkerCapability<&my_work>)として渡されるため、以下のシグネチャを持つ関数でなければなりません。最初のコンストラクタ引数はスレッド名サフィックスです。オプションの2番目の引数は制御 sys var 名をオーバーライドします。
作業関数シグネチャ
reason はサーバーが関数を呼び出した理由を示します。thread はサーバー所有のハンドルです(最初の VEF_WAKEUP_ENABLE 呼び出し時は NULL — 以下参照)。arg は記述子に登録された不透明ポインタで、変更されずに渡されます。
Wakeup ライフサイクル
サーバーは4つの理由のいずれかで作業関数を呼び出します:
理由が
VEF_WAKEUP_ENABLE の場合、thread パラメータは NULL です。この時点でスレッドハンドルはまだ存在しないためです。他の3つの理由では thread は非 NULL です。
Wakeup 戻り値
vef_next_wakeup_t を返し、次回のワーカー起動設定を更新します。各フィールドのゼロ値は「現在の設定を維持」を意味します — 両方を変更しない場合は値初期化構造体を返します(return {};)。
新しい poll ファイルディスクリプタを設定するには、その値を返します(0より大きい必要があります)。既存の poll ファイルディスクリプタをクリアするには、poll_fd に -1 を返します。
理由が VEF_WAKEUP_DISABLE の場合、戻り値は無視されます。
スレッド名と制御変数
記述子の2つのフィールドが命名を制御します:suffix— スレッド名サフィックス。サーバーは拡張機能名を前置し、my_ext/monitorのようなスレッド名を生成します。var_name— オプション。NULL でない場合、サーバーはこの名前を制御システム変数として登録します。NULL の場合、サーバーはデフォルトパターン{suffix}_enabledを使用します。
monitor を持つ拡張機能 my_ext の場合、変数は my_ext.monitor_enabled です。
ON に設定するとワーカーが開始されます。サーバーは VEF_WAKEUP_ENABLE で作業関数を呼び出してからスレッドを作成するため、その最初の呼び出しが終了するまで文は戻りません。ワーカーがすでに実行中に再度 ON に設定しても何も起こりません。OFF に設定した場合、スレッドが終了した後に戻ります。サーバーはその両方の前後でグローバルなシステム変数ロックを解放するため、作業関数はシステム変数を読み取れますが、VEF_WAKEUP_DISABLE の間に実行したクエリは行を返しません。
完全な例
単一の定期ワーカーを備えた最小限の拡張機能で、タイマー刻みごとにハートビートカウンターをインクリメントします。vsql_allow_preview_extensions = ON が設定されている場合)、サーバーは拡張機能名の下に heartbeat_enabled システム変数を登録します。my_ext という名前の拡張機能の場合、ワーカーを有効化するには:
SQL クエリ
sql_query 機能(vsql::preview::sql_query)は、バックグラウンドスレッドから SQL 文を実行できるようにします。クエリは機能の vtable を介してサーバー内部で実行され、拡張機能は MySQL クライアントライブラリをリンクしません。
機能名 VEF_PREVIEW_SQL_QUERY_NAME は "vsql::preview::sql_query" です。
機能の宣言
ヘッダーを含め、ファイルスコープでSqlQueryCapability を宣言し、.with() に渡します。通常、ThreadWorkerCapability と共に登録されます。セッションはワーカーのコールバックから開かれるためです:
g_sql.open(handle) は Session を返します。使用前に operator bool でチェックしてください。無効な Session は機能 vtable がバインドされていないか、サーバーがセッションを割り当てられなかったことを示します。Session はムーブオンリーで、破棄時に自動的に閉じられます。
クエリの実行
Session は session.sql(sv) で SqlQuery を生成します。クエリは2つのモードで実行できます:
execute()— 文を実行し、完全な結果セットをResultにバッファリングします。next()を呼び出して行をイテレートします。for_each(fn)— 文を実行し、行が生成されるたびにfnを1回呼び出します。バッファリングしません。返されるResultには診断情報のみ(行なし)が含まれます。
Result を返します。非 NULL の Result は文が成功したことを意味しません — has_error() を呼び出して確認してください。
バッファリング(execute):
column_str() は string_view を返します。これは次の next() 呼び出しまたは Result 破棄まで有効です。より長い寿命が必要な場合はコピーしてください。data() == nullptr の string_view は SQL NULL を示します。
ストリーミング(for_each):
Row はコールバックの実行中のみ有効です — 行間で参照を保持しないでください。for_each が返す Result はバッファリングされた行を持たず、next() はデータを返しません。has_error()、error()、warning_count()、warning(i) のみに使用してください。
診断
execute() および for_each() は返される Result を介して診断情報を返します。診断は1つの Diag です:
Result は以下を公開します:
error() は文が成功した場合、デフォルト構築された Diag(errno_ == 0)を返します。warning(i) は i >= warning_count() の場合、デフォルト構築された Diag を返します。
sqlstate および message のビューは Result が所有するストレージを指しており、Result が破棄されると無効になります — Result の生存期間を超えて保持する必要がある場合はコピーしてください。