Import and Export Interfaces

In this lesson, you will learn how to design efficient boundary layers for passing complex data structures between a Wasm module and its host environment.

When bridging Rust-compiled Wasm modules with a host (like a browser or a server-side runtime), you face a fundamental constraint: Wasm instances operate within a private, linear memory sandbox. You cannot simply pass a Rust struct pointer across the boundary, as the host cannot natively interpret Rust's memory layout or safety requirements.

The Boundary Layer Pattern

To bridge this, we treat the boundary as an FFI (Foreign Function Interface) zone. The goal is to minimize the overhead of moving data by using shared memory buffers and canonicalized data formats.

Instead of passing complex objects directly, we serialize data into a flat, predictable format (like a repr(C) struct or a byte slice) within the Wasm memory. We then pass the starting pointer and the length of that buffer to the host.

Consider this export interface:

#[repr(C)]
pub struct DataPayload {
    pub id: u32,
    pub value: f32,
}

#[no_mangle]
pub extern "C" fn get_payload() -> *const DataPayload {
    static PAYLOAD: DataPayload = DataPayload { id: 1, value: 42.0 };
    &PAYLOAD
}

Designing the Exchange

1. Memory Allocation: Since the host cannot allocate memory inside the Wasm heap, the Wasm module must provide an exported function (e.g., wasm_malloc) so the host can request space for data sent into the module.
2. Canonicalization: By using #[repr(C)], you guarantee the memory layout matches what the host expects, preventing issues where the compiler optimizes struct padding differently between the two environments.
3. Buffer Handles: The most efficient way to pass large structures is to have the Wasm module write to a buffer and return a "handle" (a pointer/length pair). The host then reads this range directly from the Wasm memory space.

By designing these boundaries as thin, extern "C" layers, you avoid the cost of heavy serialization (like JSON) and keep the overhead limited to simple memory copies or pointer arithmetic, maintaining the performance goals we’ve established in our previous memory layout and ABI discussions.

Key Takeaway: Efficient Wasm-Host communication relies on exporting repr(C) structures and memory-management functions that allow the host to treat a portion of the Wasm linear memory as a predictable, shared data buffer.