Crate xabi 

Stable ABI building blocks for Rust dynamic module systems.

xabi provides a small C-compatible ABI surface for hosts and dynamically loaded modules. The high-level path is:

• define an ABI trait with xabi,
• aggregate exported implementations with module,
• load the dynamic module with load or Module::load,
• use the generated XabiV1HandleTrait* handle on the host side.

Define a trait ABI

pub const TRAIT_ID: &str = "xabi.example.Demo";
pub const ABI_VERSION: u32 = 1;

#[xabi::data]
#[derive(Clone, Copy)]
pub struct BuildInput {
    pub value: u64,
}

#[xabi::xabi(id = TRAIT_ID, version = ABI_VERSION)]
pub trait Demo {
    fn name(&self) -> String;
    async fn build(&self, input: BuildInput) -> xabi::Result<Vec<u8>>;
    async fn load(&self, details: &[u8]) -> xabi::Result<()>;
}

Export an implementation

#[derive(Default)]
struct DemoImpl;

#[xabi::module]
mod exports {
    use super::*;

    #[xabi::xabi(name = "demo", version = 1)]
    impl Demo for DemoImpl {
        fn name(&self) -> String {
            "demo".to_string()
        }

        async fn build(&self, input: BuildInput) -> xabi::Result<Vec<u8>> {
            Ok(input.value.to_le_bytes().to_vec())
        }

        async fn load(&self, _details: &[u8]) -> xabi::Result<()> {
            Ok(())
        }
    }
}

Structs

Module

Loaded xabi module with a validated manifest.

ModuleHandle

Reference-counted handle for a loaded xabi module.

SendPtr

Sendable wrapper for raw pointers that are only dereferenced on a known-safe thread.

XabiBytes

Borrowed byte slice passed across the ABI boundary.

XabiContractLayout

Layout metadata for a generated xabi contract.

XabiErrorWire

Wire representation for Error when it is used as an crate::XabiType.

XabiExport

Export descriptor in an xabi module manifest.

XabiFieldLayout

Layout metadata for a C-compatible field.

XabiFuture

Future handle returned by async xabi vtable methods.

XabiFutureHandle

Rust Future wrapper around a foreign XabiFuture.

XabiLayout

A generated xabi contract layout.

XabiManifest

Static manifest exported by an xabi module.

XabiOption

Optional xabi payload.

XabiOwnedBytes

Owned byte payload returned across the ABI boundary.

XabiResult

Status plus optional owned payload returned by the future poll ABI.

XabiSlice

Borrowed typed slice passed across the ABI boundary.

XabiStr

Borrowed UTF-8 string passed across the ABI boundary.

XabiTypeLayout

Layout metadata for a C-compatible type.

XabiTypedFuture

Rust Future wrapper that decodes typed export errors.

XabiVTableLayout

Prefix metadata for a generated vtable.

XabiWaker

Waker handle passed into the xabi future poll ABI.

Enums

Error

Error type used by xabi runtime helpers.

XabiCallError

Error returned by generated host-side xabi handles.

XabiLayoutItem

One item in a xabi layout snapshot.

XabiLayoutStability

Stability rules for a type layout.

Constants

ABI_VERSION

Version of xabi’s core runtime structures.

CAP_NONE

Empty capability bitset for xabi descriptors.

ERR_EXPORT

The export reported an error.

ERR_HOST

A host callback reported an error.

ERR_INVALID_ARGUMENT

The caller provided an invalid argument.

ERR_PANIC

The callee caught a panic before it crossed the ABI boundary.

OK

Successful FFI status code.

POLL_PENDING

A future is still pending.

POLL_READY

A future completed and wrote an crate::XabiResult.

Traits

XabiContract

Trait implemented by ABI descriptors generated by crate::xabi.

XabiLayoutCollector

Collector used by generated layout descriptors.

XabiLayoutSource

A generated source of xabi layout entries.

XabiType

Rust type that has a stable xabi representation.

Functions

catch_unwind_code

Convert a panic-catching FFI closure into a status code.

catch_unwind_or

Convert a panic-catching closure into a caller-provided default value.

catch_unwind_owned

Convert a panic-catching FFI closure into an owned byte payload.

load^⚠

Load an xabi module from a native library path.

status_to_result

Convert a raw xabi status code into a Result.

validate_abi_version

Validate that an ABI structure uses the expected version.

validate_size

Validate that an ABI structure is at least as large as the required prefix.

Type Aliases

Result

Result type used by xabi runtime helpers.

Attribute Macros

data

Mark a Rust struct as a stable xabi data type.

module

Aggregate implementation exports from an inline Rust module.

opaque

Mark a single-pointer Rust struct as an opaque xabi handle.

xabi

Mark a Rust item as participating in xabi ABI generation.