abi_adapter/lib.rs
1//! Slot-based wrappers for Wasm ABI boundaries.
2//!
3//! Each slot is a Rust `u32` and a Wasm `i32`; `[u32; N]` holds `N` slots.
4//!
5//! # API
6//!
7//! - [`abi!`]: declare a host wrapper or guest export.
8//! - [`FromSlots`]: decode business arguments.
9//! - [`IntoSlots`]: encode business results.
10//!
11//! Repository guides: `docs/guide.md` for usage and common problems and
12//! `docs/architecture.md` for design.
13//!
14//! # Example
15//!
16//! ```
17//! use abi_adapter::abi;
18//!
19//! fn double(x: u32) -> u32 {
20//! x * 2
21//! }
22//!
23//! abi! { host pub fn double_abi([x]) -> 1 => crate::double; }
24//!
25//! fn main() {
26//! assert_eq!(double_abi(21), 42);
27//! }
28//! ```
29//!
30//! # Built-in conversions
31//!
32//! These types implement both [`FromSlots`] and [`IntoSlots`].
33//!
34//! | Type | Slots | Representation |
35//! | --- | --- | --- |
36//! | `()` | 0 | `[]` |
37//! | `u32` | 1 | Unchanged |
38//! | `i32` | 1 | Original bits; `-1` becomes `0xffff_ffff` |
39//! | `f32` | 1 | `to_bits` / `from_bits`, without a numeric cast |
40//! | `[u32; N]` | N | Unchanged, including `N = 0` |
41//!
42//! Implement the required direction for custom types. [`abi!`] directly
43//! returns only zero or one slot, regardless of a type's other conversions.
44//!
45//! # Constraints
46//!
47//! The crate is `no_std`, has no dependencies, allocates no heap memory, and
48//! generates no `unsafe` blocks. User conversions and business functions
49//! retain their own allocation and error behavior. Guest declarations emit
50//! `#[unsafe(export_name = ...)]`; users must uphold the export-name and
51//! signature requirements documented by [`abi!`].
52
53#![no_std]
54#![forbid(unsafe_code)]
55
56mod boundary;
57mod impls;
58mod slots;
59
60pub use slots::{FromSlots, IntoSlots};