Struct PluginVTable 

#[repr(C)]
pub struct PluginVTable {
    pub api_version: u32,
    pub create: extern "C" fn() -> RResult<*mut c_void, RBoxError>,
    pub destroy: extern "C" fn(state: *mut c_void),
    pub init: extern "C" fn(state: *mut c_void, ctx: &PluginContext) -> RResult<(), RBoxError>,
    pub process: extern "C" fn(state: *const c_void, msg: &SpoeMessage) -> RResult<ProcessingResult, RBoxError>,
    pub name: extern "C" fn(state: *const c_void) -> RStr<'static>,
    pub plugin_version: extern "C" fn(state: *const c_void) -> RStr<'static>,
    pub shutdown: extern "C" fn(state: *const c_void),
    pub config_schema: extern "C" fn(state: *const c_void) -> ROption<RString>,
    pub validate: extern "C" fn(state: *const c_void, ctx: &PluginContext) -> RVec<Diagnostic>,
    pub set_metric_recorder: extern "C" fn(state: *mut c_void, record_fn: RecordMetricFn, ctx: *const c_void),
}

The function table a plugin shared library exports.

#[repr(C)] is mandatory: it pins field offsets and padding rules so plugins built against an older version of this crate keep working when the hub is built against a newer one (and vice versa).

Safety contract for hosts

Fields below the v1 baseline marker are version-gated. Hosts MUST NOT access them via &PluginVTable directly — the borrow would implicitly cover the whole struct, which on an older plugin is past the end of its allocation. Use the read_*_field accessors or read individual fields through the raw pointer (e.g. unsafe { (*ptr).api_version }) which read only the bytes for that field.

Fields

api_version: u32

Plugin’s reported API version. The hub uses this to gate access to fields beyond the v1 baseline.

create: extern "C" fn() -> RResult<*mut c_void, RBoxError>

Factory: allocate and return a new plugin state pointer. RErr aborts plugin loading.

destroy: extern "C" fn(state: *mut c_void)

Destructor: free the plugin state pointer. Called once at hub shutdown or when a plugin fails post-create. MUST tolerate being called with a state pointer that init() has not yet observed.

init: extern "C" fn(state: *mut c_void, ctx: &PluginContext) -> RResult<(), RBoxError>

Initialize the plugin. Called once after create and any schema/validate pre-checks. RErr aborts plugin loading.

process: extern "C" fn(state: *const c_void, msg: &SpoeMessage) -> RResult<ProcessingResult, RBoxError>

Handle one SPOE message. Called per request. The implementation is wrapped in catch_unwind by the define_plugin! macro so a panic does not abort the hub process.

name: extern "C" fn(state: *const c_void) -> RStr<'static>

Plugin’s display name. Borrowed for the lifetime of the plugin instance (until destroy is called). Plugins typically return a &'static str literal.

plugin_version: extern "C" fn(state: *const c_void) -> RStr<'static>

Plugin’s SemVer string. Same lifetime contract as name.

shutdown: extern "C" fn(state: *const c_void)

Shutdown hook. Called once before destroy.

config_schema: extern "C" fn(state: *const c_void) -> ROption<RString>

Optional JSON Schema string for config validation. RNone skips schema validation. The default define_plugin! macro emits a thunk that returns RNone when the plugin author has not declared one.

validate: extern "C" fn(state: *const c_void, ctx: &PluginContext) -> RVec<Diagnostic>

Deep config validation. Returns an empty RVec when the plugin’s config is valid. Errors block loading; warnings are surfaced but do not block.

set_metric_recorder: extern "C" fn(state: *mut c_void, record_fn: RecordMetricFn, ctx: *const c_void)

Install the hub’s metric recorder on the plugin. Called by the hub once between create and init, so the plugin can emit metrics from init onward. The plugin stores the record_fn and ctx (typically inside a MetricRecorder field of its state) and invokes record_fn(ctx, ...) for every metric event. The recorder remains valid until destroy returns; the hub guarantees lifetime, the plugin guarantees not to call it after destroy.

Plugins that don’t want metrics still need to provide a thunk (the define_plugin! macro emits a no-op default) — the field is unconditionally read on v2 hubs.

Host access: gated on api_version >= PLUGIN_API_VERSION_V2. Reading this field on a v1 plugin’s vtable is UB — the v1 allocation does not include these bytes.

Implementations

impl PluginVTable

pub unsafe fn read_api_version(vtable_ptr: *const PluginVTable) -> u32

Read just the api_version field of a plugin’s vtable.

Safety

vtable_ptr must be a non-null pointer to a PluginVTable allocation that is at least 4 bytes long (every plugin has at least the api_version field).

pub unsafe fn read_set_metric_recorder( vtable_ptr: *const PluginVTable, ) -> Option<extern "C" fn(state: *mut c_void, record_fn: RecordMetricFn, ctx: *const c_void)>

Read the v2 set_metric_recorder field, returning None for plugins built against v1 (whose allocation doesn’t include it).

Safety

vtable_ptr must be a non-null pointer to a PluginVTable allocation produced by a published plugin (i.e. consistent with the api_version field’s claim about which fields are present). On v1 plugins this function reads only api_version and returns None without touching past the v1 baseline.