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>,
}

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.

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).