Module shell

Expand description

The plugin side of the ABI: everything between export!’s shims and the trait a plugin writes.

This is the only module in the crate that touches raw memory. It owns three jobs:

Answer the host’s questions through the accessors (dispatch is what export! points the command capability at),
Build the typed Context out of them, so a plugin never sees a key or a pointer,
Hand the answer back in the ABI’s shape, with the memory this side owns.

Everything here runs inside the plugin, on data the host lent it. The rules it obeys:

Nothing lent may be kept past the call.
Memory is freed by the side that allocated it: what this module leases out for the answer is reclaimed by free_command / free_str, never by the host.
A panic must not cross: the shims in export! wrap every entry point in catch_unwind.

Constants§

BUILD_RUSTC: The rustc version this crate was built with, injected by build.rs. Diagnostics only.
BUILD_TARGET: The target this crate was built for, injected by build.rs. Diagnostics only.
PANIC_MARKER: What name / family answer when the plugin panicked before it could answer at all.

dispatch^⚠: The plugin-side entry point export! exposes as the command capability.
dispatch_free_command^⚠: The free_command shim’s implementation.
dispatch_free_str^⚠: The free_str shim’s implementation.
free_command^⚠: Release everything write_command allocated, without touching the struct itself (it lives on the host’s stack).
free_str^⚠: Give one string back to this side’s allocator.
guard: Wrap one cross-boundary call in catch_unwind.
guard_str: The same, for one of the two -> PmpxStr shims.
install_log_table^⚠: Install the host’s logging table, after the caller has checked its size.
leak_bytes: Lease out bytes for the host to read.
leak_str: Lease out text for the host to read.
read_os^⚠: Read a borrowed C string as an owned OsString, losslessly where the platform allows it.
read_str^⚠: Read a borrowed C string as text, checking UTF-8.
remember_name: Remember the plugin’s own name, for the no-host fallback.
write_command^⚠: Write a CommandSpec in its cross-boundary form, with the memory allocated by this side.