Copyright	(c) 2026 Tushar Adhatrao
License	MIT
Stability	experimental
Safe Haskell	None
Language	GHC2021

WasmEdge.Memory.Alloc

Contents

High-level buffer call (single argument)
High-level buffer call (two arguments)
Manual allocation primitives
Convention configuration
Type aliases

Description

Provides a high-level API for calling WebAssembly functions that accept or return heap-allocated data. This module implements the standard __guest-side allocation__ convention:

The Wasm guest module exports: * alloc(size: i32) -> i32 — allocate size bytes, return pointer * dealloc(ptr: i32, len: i32) — free a previously allocated buffer
The Haskell host serialises the input with wasmPoke, calls the Wasm function with (ptr, len), and deserialises the output.

This convention is compatible with the allocator produced by Rust's #[no_mangle] pub fn alloc(size: usize) -> *mut u8 pattern and with the wasmedge-sdk Rust examples in this repository.

Quick start

-- Register the module first:
registerModuleFromFile vm "my_module" "my_module.wasm" >>= throwOnFail

-- Then call a function that takes Text (ptr, len) and returns Text (ptr, len):
result <- withWasmBuffer vm "my_module" "greet" defaultConvention (Hello :: Text)
case result of
  Left err  -> print err
  Right txt -> putStrLn txt

See withWasmBuffer2 for two-argument variants.

Return value encoding

The Wasm function must return a (ptr: i32, len: i32) pair. We support two common encodings:

PackedI64 — packed into a single i64: ptr << 32 | len. This is allocation-free on the guest side.
SeparateI32s — two separate i32 return values.

Synopsis

withWasmBuffer :: (WasmMemory a, WasmMemory b) => VM -> ModuleName -> FunctionName -> AllocConvention -> a -> IO (WasmResult b)
withWasmBuffer2 :: (WasmMemory a, WasmMemory b, WasmMemory c) => VM -> ModuleName -> FunctionName -> AllocConvention -> a -> b -> IO (WasmResult c)
wasmAlloc :: VM -> ModuleName -> AllocConvention -> Word32 -> IO (WasmResult Word32)
wasmDealloc :: VM -> ModuleName -> AllocConvention -> Word32 -> Word32 -> IO (WasmResult ())
data AllocConvention = AllocConvention {
- allocFunc :: FunctionName
- deallocFunc :: FunctionName
- resultEncoding :: ResultEncoding
- scratchSize :: Word32
}
data ResultEncoding
- = PackedI64
- | SeparateI32s
defaultConvention :: AllocConvention
type ModuleName = Text
type FunctionName = Text

High-level buffer call (single argument)

withWasmBuffer #

Arguments

:: (WasmMemory a, WasmMemory b)
=> VM
-> ModuleName
-> FunctionName
-> AllocConvention
-> a	Input value to serialise
-> IO (WasmResult b)

The primary high-level API for calling a Wasm function that takes a serialised buffer and returns a serialised buffer.

The Wasm function must have the signature (depending on ResultEncoding):

PackedI64: (ptr: i32, len: i32) -> i64
SeparateI32s: (ptr: i32, len: i32) -> (i32, i32)

Internally, this bracket:

Allocates a scratch buffer in Wasm linear memory via the alloc export.
Serialises the input a into that buffer using wasmPoke.
Calls the Wasm function with (inputPtr, inputLen).
Decodes the return value as (retPtr, retLen).
Reads and deserialises b from Wasm memory at (retPtr, retLen).
Deallocates both the input and output buffers via dealloc.

Returns Left if any step fails. Deallocation is attempted on all error paths.

High-level buffer call (two arguments)

withWasmBuffer2 :: (WasmMemory a, WasmMemory b, WasmMemory c) => VM -> ModuleName -> FunctionName -> AllocConvention -> a -> b -> IO (WasmResult c) #

Like withWasmBuffer but for Wasm functions that take two buffer arguments.

Expected Wasm signature (PackedI64):

(aPtr: i32, aLen: i32, bPtr: i32, bLen: i32) -> i64

Manual allocation primitives

wasmAlloc #

Arguments

:: VM
-> ModuleName
-> AllocConvention
-> Word32	Number of bytes to allocate
-> IO (WasmResult Word32)

Allocate n bytes inside a Wasm module's linear memory by calling the module-exported alloc function.

Returns the pointer (as Word32) on success, or Left on failure.

wasmDealloc #

Arguments

:: VM
-> ModuleName
-> AllocConvention
-> Word32	Pointer returned by `wasmAlloc`
-> Word32	Length in bytes
-> IO (WasmResult ())

Free a previously-allocated Wasm buffer by calling the module-exported dealloc function.

Convention configuration

data AllocConvention #

Configuration for the guest allocator naming convention.

Constructors

AllocConvention

Fields

allocFunc :: FunctionName
Name of the allocator export. Default: "alloc". Expected signature: (i32 size) -> i32 ptr
deallocFunc :: FunctionName
Name of the deallocator export. Default: "dealloc". Expected signature: (i32 ptr, i32 len)
resultEncoding :: ResultEncoding
How the called Wasm function returns a (ptr, len) result.
scratchSize :: Word32
Scratch buffer size in bytes allocated for each call. Default: 65536 (64 KiB).

data ResultEncoding #

How a Wasm function encodes its buffer result.

Most idiomatic Rust guest code uses PackedI64. wasm-bindgen uses SeparateI32s.

Constructors

PackedI64	`ptr` packed into upper 32 bits, `len` in lower 32 bits of a single `i64`. Guest: `return ((ptr as i64) << 32) \| (len as i64)`
SeparateI32s	Two separate `i32` return values: `[WasmI32 ptr, WasmI32 len]`.

defaultConvention :: AllocConvention #

The default convention: alloc, dealloc, packed i64 result, 64 KiB scratch.

Type aliases

type ModuleName = Text #

Name of the registered Wasm module.

type FunctionName = Text #

Name of the exported Wasm function.