Skip to main content
The capabilities on this page are in preview: their APIs are not stable, and an extension that declares one requires 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 a ThreadWorkerCapability instantiated on your work function at file scope, and pass it to .with():
The work function is supplied as a non-type template argument (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

The work function returns a 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 like my_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.
The control variable is a server-registered system variable, so it takes the extension name as a component prefix. For extension 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.
With this extension installed (and 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".
A SQL session must be opened from a thread-worker callback using that callback’s vef_thread_handle_t *. open() is not valid from VDFs or from arbitrary extension-created threads — it requires the worker session context.

Declaring the Capability

Include the header, declare a SqlQueryCapability 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

A Session 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 a Result. Iterate rows by calling next() at the caller’s pace.
  • for_each(fn) — runs the statement and invokes fn once per row as rows are produced, without buffering. The returned Result carries diagnostics only (no rows).
Both return a 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):
The 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

Both execute() 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.

Complete Example

A worker that runs one buffered query and one streaming query on each tick, logging diagnostics from both: