Module abi 

The C ABI a runtime plugin exports and the engine loads.

Everything that crosses the boundary is bytes and C scalars: the init context, the manifest a plugin answers with, and every call travel as bincode buffers (see crate::codec), never as Rust types, so a plugin built by any compiler works against any engine built from the same release tag. Compatibility is enforced by the handshake fields on Desc, not by hoping both sides agree.

Desc and HostVtable are what make this the runtime’s ABI; the buffer, the hook signature, and the status codes below come from lumen_plugin_abi::raw and mean the same thing at every Lumen plugin boundary.

Threading

Desc::init, Desc::call, and Desc::shutdown run on the engine’s tick thread, one at a time; the engine never calls into a plugin from a background thread and never re-enters it from inside a host callback. The HostVtable entries go the other way and have the opposite contract: they are callable from any thread at any time, including while a call is running, which is what lets a plugin own a worker thread.

Structs

Buf

A byte buffer allocated by the plugin. The host reads it, then returns it through the plugin’s own free function; it never frees plugin memory with its own allocator.

Desc

The descriptor a plugin’s entry function returns. Lives for the process; the host reads it after the handshake below.

HostVtable

What the host offers a plugin: an opaque context pointer and the calls a plugin makes back into the engine.

Enums

LogLevel

How loud a line handed to HostVtable::log is.

Constants

ABI_VERSION

Version of this descriptor layout and of the SDK-owned wire shapes. Bump on any change to Desc, HostVtable, Buf, the status codes, or any serde type this crate sends across the boundary (InitCx, Manifest, Call, CallOut); the lumen_script types - PluginEvent among them - are covered by Desc::script_wire_version instead.

ENTRY

The one symbol a plugin cdylib exports: unsafe extern "C" fn lumen_plugin_v1() -> *const Desc.

ERR

out holds a UTF-8 error message; the call fails with it.

FLAG_PANIC_ABORT

Set in a descriptor’s flags by a plugin built with panic = "abort". The host refuses such a plugin at load: the panic-to-error contract depends on unwinding, and an aborting plugin would kill the host on any hook panic.

OK

out holds the hook’s payload.

PANICKED

The hook panicked; out holds the panic message.

UNCHANGED

out is empty; the host keeps the input unchanged.

Type Aliases

FreeFn

Frees a buffer previously returned by any hook of the same plugin.

HookFn

One hook entry point. input/ctx are borrowed for the call; on return the status code says what out holds.

InitFn

Bring a plugin up: hand it the init context and the host callbacks, and take back its manifest.