vsql_allow_preview_extensions = ON to install. See Preview Capabilities for how to enable the preview tier and register a capability.
Thread Worker
The thread worker capability (vsql::preview::thread_worker) lets an
extension run a background thread driven by the server. The thread is started
and stopped via a control system variable that the server registers at
extension load; the server invokes the extension’s work function on a periodic
timer, on file-descriptor readiness, or in response to enable/disable events.
The capability name VEF_PREVIEW_THREAD_WORKER_NAME is
"vsql::preview::thread_worker".
Declaring the Capability
Include the header, declare aThreadWorkerCapability instantiated on your
work function at file scope, and pass it to .with():
ThreadWorkerCapability<&my_work>), so it must be a function with the
signature shown below. The first constructor argument is the thread-name
suffix; the optional second argument overrides the control sys var name.
Work Function Signature
reason indicates why the server called the function. thread is the
server-owned handle for this worker (NULL on the initial VEF_WAKEUP_ENABLE
call — see below). arg is the opaque pointer registered on the descriptor;
it is passed through unchanged.
Wakeup Lifecycle
The server calls the work function with one of four reasons:
The
thread parameter is NULL when the reason is VEF_WAKEUP_ENABLE, because
the thread handle does not exist yet at that point. For the other three
reasons, thread is non-null.
Wakeup Return Value
vef_next_wakeup_t to update the next wakeup
configuration. A zero value in either field means “keep the current setting”
— return a value-initialized struct (return {};) to leave both unchanged.
To set a new poll file descriptor, return its value (must be greater than
zero). To clear an existing poll file descriptor, return -1 in poll_fd.
The return value is ignored when the reason is VEF_WAKEUP_DISABLE.
Thread Name and Control Variable
Two fields on the descriptor control naming:suffix— the thread-name suffix. The server prepends the extension name, producing thread names likemy_ext/monitor.var_name— optional. When non-null, the server registers this exact name as the control system variable. When null, the server uses the default pattern{suffix}_enabled.
my_ext with suffix
monitor, the variable is my_ext.monitor_enabled.
Setting it ON starts the worker: the server calls the work function with
VEF_WAKEUP_ENABLE, then creates the thread, so the statement does not return
until that first call has finished. Setting it ON again while the worker is
already running does nothing. Setting it OFF returns after the thread has
exited. The server releases its global system-variable lock around both, so the work function may read system variables, but a query it runs during VEF_WAKEUP_DISABLE does not return any rows.
Complete Example
A minimal extension with a single periodic worker that increments a heartbeat counter on each timer tick.vsql_allow_preview_extensions = ON), the
server registers a heartbeat_enabled system variable under the extension’s
name. For an extension named my_ext, enable the worker with:
SQL Query
The sql_query capability (vsql::preview::sql_query) lets an extension
execute SQL statements from a background thread. Queries run inside the
server through the capability vtable — extensions do not link against any
MySQL client library.
The capability name VEF_PREVIEW_SQL_QUERY_NAME is
"vsql::preview::sql_query".
Declaring the Capability
Include the header, declare aSqlQueryCapability at file scope, and pass it
to .with(). It is typically registered alongside a ThreadWorkerCapability,
since sessions are opened from the worker callback:
g_sql.open(handle) returns a Session. Check it with operator bool before
use; an invalid Session indicates the capability vtable was not bound or the
server could not allocate a session. The Session is move-only and closes
itself on destruction.
Executing Queries
ASession produces a SqlQuery via session.sql(sv). The query can be run
in two modes:
execute()— runs the statement and buffers the full result set in aResult. Iterate rows by callingnext()at the caller’s pace.for_each(fn)— runs the statement and invokesfnonce per row as rows are produced, without buffering. The returnedResultcarries diagnostics only (no rows).
Result. A non-null Result does not mean the statement
succeeded — call has_error() to find out.
Buffered (execute):
column_str() returns a string_view that is valid only until the next
next() call or until Result is destroyed. Copy it if a longer lifetime is
needed. A string_view with data() == nullptr indicates SQL NULL.
Streaming (for_each):
Row passed to the callback is valid only for the duration of the call —
do not store references to it across rows. The Result returned by
for_each holds no buffered rows; next() on it will not yield data. Use it
only for has_error(), error(), warning_count(), and warning(i).
Diagnostics
Bothexecute() and for_each() surface diagnostics through the returned
Result. A diagnostic is one Diag:
Result exposes:
error() returns a default-constructed Diag (errno_ == 0) when the
statement succeeded. warning(i) returns a default-constructed Diag when
i >= warning_count().
The sqlstate and message views point into storage owned by the Result
and become invalid when the Result is destroyed — copy them if they need to
outlive it.