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

Raw owned-byte descriptor passed across the ABI boundary.

XabiOwnedBytesOwner

Safe RAII owner for a producer-owned byte payload.

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 values and 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_exact_size

Validate that an ABI structure has exactly the expected size.

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.