Struct FolditPluginVtable 

#[repr(C)]
pub struct FolditPluginVtable {

    pub abi_version: u32,
    pub padding: u32,
    pub create: unsafe extern "C" fn(config_json: *const c_char, config_len: usize) -> FolditPluginHandle,
    pub destroy: unsafe extern "C" fn(handle: FolditPluginHandle),
    pub register: unsafe extern "C" fn(handle: FolditPluginHandle, out_buf: *mut FolditPluginBuffer, out_err: *mut FolditPluginError) -> FolditPluginStatus,
    pub init: unsafe extern "C" fn(handle: FolditPluginHandle, assembly: *const u8, assembly_len: usize, assets: *const FolditPluginAsset, assets_len: usize, params: *const FolditPluginParamEntry, params_len: usize, out_session: *mut u64, out_initial_buf: *mut FolditPluginBuffer, out_err: *mut FolditPluginError) -> FolditPluginStatus,
    pub update_assembly: unsafe extern "C" fn(handle: FolditPluginHandle, session: u64, payload_kind: FolditPluginAssemblyPayloadKind, bytes: *const u8, bytes_len: usize, from_gen: u64, to_gen: u64, out_err: *mut FolditPluginError) -> FolditPluginStatus,
    pub drop_session: unsafe extern "C" fn(handle: FolditPluginHandle, session: u64, out_err: *mut FolditPluginError) -> FolditPluginStatus,
    pub invoke: unsafe extern "C" fn(handle: FolditPluginHandle, session: u64, op_id: *const u8, op_id_len: usize, ctx: *const FolditPluginDispatchContext, params: *const FolditPluginParamEntry, params_len: usize, out_assembly: *mut FolditPluginBuffer, out_err: *mut FolditPluginError) -> FolditPluginStatus,
    pub start_stream: unsafe extern "C" fn(handle: FolditPluginHandle, session: u64, op_id: *const u8, op_id_len: usize, ctx: *const FolditPluginDispatchContext, params: *const FolditPluginParamEntry, params_len: usize, request_id: u64, out_err: *mut FolditPluginError) -> FolditPluginStatus,
    pub poll_stream: unsafe extern "C" fn(handle: FolditPluginHandle, request_id: u64, out_buf: *mut FolditPluginBuffer, out_err: *mut FolditPluginError) -> FolditPluginStatus,
    pub update_stream: unsafe extern "C" fn(handle: FolditPluginHandle, request_id: u64, params: *const FolditPluginParamEntry, params_len: usize, out_err: *mut FolditPluginError) -> FolditPluginStatus,
    pub cancel_stream: unsafe extern "C" fn(handle: FolditPluginHandle, request_id: u64, out_err: *mut FolditPluginError) -> FolditPluginStatus,
    pub query: unsafe extern "C" fn(handle: FolditPluginHandle, session: u64, query_id: *const u8, query_id_len: usize, ctx: *const FolditPluginDispatchContext, params: *const FolditPluginParamEntry, params_len: usize, assembly: *const u8, assembly_len: usize, out_data: *mut FolditPluginBuffer, out_err: *mut FolditPluginError) -> FolditPluginStatus,
    pub free_buffer: unsafe extern "C" fn(buf: *mut FolditPluginBuffer),
    pub free_error: unsafe extern "C" fn(err: *mut FolditPluginError),
}

Function-pointer table exported by every native plugin dylib.

The plugin exports a single C symbol (foldit_plugin_vtable) that returns *const FolditPluginVtable. The host calls this once at load time, validates abi_version, and stores the pointer.

Fields

abi_version: u32

MUST equal FOLDIT_PLUGIN_ABI_VERSION - host rejects the dylib otherwise.

padding: u32

Padding to 8-align the following function pointers.

create: unsafe extern "C" fn(config_json: *const c_char, config_len: usize) -> FolditPluginHandle

Construct a plugin instance from a UTF-8 JSON-encoded config dict. Returns null on failure.

destroy: unsafe extern "C" fn(handle: FolditPluginHandle)

Free the plugin instance. Called once; safe to assume no in-flight calls when invoked.

register: unsafe extern "C" fn(handle: FolditPluginHandle, out_buf: *mut FolditPluginBuffer, out_err: *mut FolditPluginError) -> FolditPluginStatus

Returns serialized proto::PluginRegistration (registration is nested + only called once per session, so paying the proto cost here is fine).

init: unsafe extern "C" fn(handle: FolditPluginHandle, assembly: *const u8, assembly_len: usize, assets: *const FolditPluginAsset, assets_len: usize, params: *const FolditPluginParamEntry, params_len: usize, out_session: *mut u64, out_initial_buf: *mut FolditPluginBuffer, out_err: *mut FolditPluginError) -> FolditPluginStatus

Open a session with the initial assembly bytes. Writes the assigned session id to *out_session on success. assets carries the puzzle assets (e.g. a density map, ligand params) as borrowed name+bytes views valid only for this call. Also writes assembly bytes of the assembly the plugin settled on after any post-Init normalization (e.g. Rosetta builds a full-atom pose from the input, which may add missing atoms, hydrogens, or terminal O, changing the atom count) into *out_initial_buf. Plugins with no normalization step write an empty buffer; host then keeps its input assembly. Host owns the buffer afterward (released via the same free_buffer path as register/score).

update_assembly: unsafe extern "C" fn(handle: FolditPluginHandle, session: u64, payload_kind: FolditPluginAssemblyPayloadKind, bytes: *const u8, bytes_len: usize, from_gen: u64, to_gen: u64, out_err: *mut FolditPluginError) -> FolditPluginStatus

Push an Assembly update to a session. The payload is either a full assembly snapshot (payload_kind = Full) or a delta edit list (payload_kind = Delta). from_gen / to_gen are the host’s broadcast generation counters; a plugin whose local gen doesn’t match from_gen should arm a STALE_GEN error to return on its next dispatch so the host re-syncs.

drop_session: unsafe extern "C" fn(handle: FolditPluginHandle, session: u64, out_err: *mut FolditPluginError) -> FolditPluginStatus

Tear down a session and release its per-session state.

invoke: unsafe extern "C" fn(handle: FolditPluginHandle, session: u64, op_id: *const u8, op_id_len: usize, ctx: *const FolditPluginDispatchContext, params: *const FolditPluginParamEntry, params_len: usize, out_assembly: *mut FolditPluginBuffer, out_err: *mut FolditPluginError) -> FolditPluginStatus

Run a one-shot op. Writes resulting assembly bytes (typically delta bytes) to *out_assembly on success.

start_stream: unsafe extern "C" fn(handle: FolditPluginHandle, session: u64, op_id: *const u8, op_id_len: usize, ctx: *const FolditPluginDispatchContext, params: *const FolditPluginParamEntry, params_len: usize, request_id: u64, out_err: *mut FolditPluginError) -> FolditPluginStatus

Start a streaming op under the host-assigned request_id. The plugin keys its stream state on that id; subsequent poll / update / cancel calls thread the same id through.

poll_stream: unsafe extern "C" fn(handle: FolditPluginHandle, request_id: u64, out_buf: *mut FolditPluginBuffer, out_err: *mut FolditPluginError) -> FolditPluginStatus

Returns serialized proto::PollStreamResponse; the host decodes the variant. Centralizing the variant set in proto keeps the C ABI surface smaller; poll_stream is the only place where the variant tagging matters.

update_stream: unsafe extern "C" fn(handle: FolditPluginHandle, request_id: u64, params: *const FolditPluginParamEntry, params_len: usize, out_err: *mut FolditPluginError) -> FolditPluginStatus

Apply a live parameter update to an active stream. Plugins may coalesce or defer updates until the next poll boundary.

cancel_stream: unsafe extern "C" fn(handle: FolditPluginHandle, request_id: u64, out_err: *mut FolditPluginError) -> FolditPluginStatus

Cancel an active stream. The plugin must release stream state before the next poll returns Final or Error.

query: unsafe extern "C" fn(handle: FolditPluginHandle, session: u64, query_id: *const u8, query_id_len: usize, ctx: *const FolditPluginDispatchContext, params: *const FolditPluginParamEntry, params_len: usize, assembly: *const u8, assembly_len: usize, out_data: *mut FolditPluginBuffer, out_err: *mut FolditPluginError) -> FolditPluginStatus

Run a read-only query (no assembly mutation). When assembly is non-null (assembly_len > 0) it names a specific composition to read/score instead of the session: committed heads or a checkpoint; null/0 operates on the session / its in-flight snapshot. Result bytes are op-defined (e.g. a serialized proto::ScoreReport for the "score" query); the caller parses them against the query contract.

free_buffer: unsafe extern "C" fn(buf: *mut FolditPluginBuffer)

Free a plugin-allocated buffer. No-op when data is null.

free_error: unsafe extern "C" fn(err: *mut FolditPluginError)

Free both inner buffers of a plugin-allocated error struct.