Struct ModuleBuilder 

#[non_exhaustive]
pub struct ModuleBuilder { /* private fields */ }

In-progress core-Wasm module.

Carries the runtime memory plus every wasm section the backend assembles; the heap-pointer global and the data section are emitted at Self::finish time so the initial heap-pointer value can be relocated past whatever string-literal data has been seeded in the meantime.

Implementations

impl ModuleBuilder

pub fn new() -> Self

Build an empty validating module with the runtime memory in place. The heap-pointer global is materialized at Self::finish time so its initial value can reflect any static data segments accumulated meanwhile.

pub fn set_function_name(&mut self, function_index: u32, name: &str)

Record a source-level name for the wasm function at function_index. Names land in the name custom section emitted at Self::finish time and let debug tooling (wasmtime --debug, browser devtools, wasm-tools print) show readable identifiers instead of func[N]. Calling for an index past the current end-of-vector grows the names vector; any unwritten slot stays anonymous.

pub fn set_static_data(&mut self, bytes: Vec<u8>)

Install bytes as the contents of the static data segment.

The segment is emitted as an active data segment at offset 0 of linear memory at Self::finish time; the heap-pointer global’s initial value is bumped past the end of the segment (rounded up to BUMP_ALLOCATOR_ALIGN) so subsequent bump- allocator calls cannot trample the data. Calling repeatedly replaces the previously-installed contents.

Module-lowering builds this buffer by concatenating the string pool’s bytes (at offset 0) with any per-impl vtable blobs. Both regions are read-only static data — strings keep header/byte offsets within the buffer; vtables store funcref-table indices that virtual-dispatch lowering loads at the call site.

pub fn declare_type(&mut self, params: &[ValType], results: &[ValType]) -> u32

Declare a wasm function-type signature without attaching a function body. Used by call_indirect lowerings that need a type-index for the call’s signature; the index is stable across the rest of the build.

pub fn declare_closure_table(&mut self, num_closures: u32) -> u32

Lazy-create the funcref Table of num_closures slots used by indirect closure invocation. Returns the table index. Calling repeatedly returns the original index without re-declaring.

pub fn populate_closure_table(&mut self, wasm_func_indices: &[u32])

Populate the closure funcref table with wasm_func_indices, in order, starting at element offset 0. The closure value’s stored funcref index is the slot number (the table’s element index), which call_indirect resolves to the function pointer at runtime.

pub const fn closure_table_index(&self) -> Option<u32>

Wasm table index of the closure funcref table if declared.

pub fn declare_method_table(&mut self, num_methods: u32) -> u32

Lazy-create the funcref Table of num_methods slots used by virtual trait-method dispatch. Returns the table index. Calling repeatedly returns the original index without re-declaring.

pub fn populate_method_table(&mut self, wasm_func_indices: &[u32])

Populate the method funcref table with wasm_func_indices, in order, starting at element offset 0. The vtable slot value stored in linear memory is the slot number (the table’s element index), which call_indirect resolves to the function pointer at runtime.

pub const fn method_table_index(&self) -> Option<u32>

Wasm table index of the method funcref table if declared.

pub fn export_function(&mut self, name: &str, function_index: u32)

Export a previously-declared function under name.

pub fn declare_function_with_body( &mut self, param_types: &[ValType], result_types: &[ValType], body: &Function, ) -> u32

Declare a function with the given param + result valtypes and a caller-supplied body. The body must already include the closing end instruction. Returns the wasm function index — accounting for the imported-function region that occupies the leading indices of the wasm function-index space.

pub fn declare_function_import( &mut self, module_name: &str, fn_name: &str, param_types: &[ValType], result_types: &[ValType], ) -> u32

Declare a wasm function import under (module_name, fn_name) with the given signature, and return the wasm function index assigned to it.

Imports occupy the leading region of the wasm function-index space — the spec orders the import section before the function section. Every call to this method must therefore happen before any Self::declare_function_with_body call whose returned index the caller intends to compare against an import’s; the helper itself bumps import_function_count so subsequent locally-defined functions land at the right offset.

pub fn declare_function( &mut self, param_types: &[ValType], result_types: &[ValType], ) -> u32

Declare a function with the given param + result valtypes and a placeholder unreachable body. Useful for tests and for laying down the function-index space before bodies are lowered.

pub fn declare_bump_allocator(&mut self) -> u32

Declare and emit the bump-allocator runtime helper, returning its wasm function index. Subsequent calls return the same index without re-emitting the function — the helper is meant to live exactly once per module.

Signature: __alloc(size: i32) -> i32 (raw byte size in, allocation address out). Each returned address is aligned up to BUMP_ALLOCATOR_ALIGN bytes; the heap pointer global is advanced past the allocation. Out-of-memory is not yet handled — callers that bust the linear-memory ceiling get a wasm trap.

pub const fn bump_allocator_index(&self) -> Option<u32>

Wasm function index of the bump allocator if it has been declared, else None.

pub fn declare_str_eq(&mut self) -> u32

Declare and emit the __str_eq runtime helper, returning its wasm function index. Subsequent calls return the same index.

Signature: __str_eq(a: i32, b: i32) -> i32. Each input is a pointer to an { ptr, len } string header. Returns 1 when the two strings have identical byte sequences, 0 otherwise.

Implementation: load both len slots; if they differ, return 0. Otherwise loop over the bytes pointed at by each ptr, comparing one byte at a time. Returns 1 once the loop runs to completion without finding a mismatch.

pub const fn str_eq_index(&self) -> Option<u32>

Wasm function index of the __str_eq helper if it has been declared, else None.

pub fn declare_str_concat(&mut self) -> u32

Declare and emit the __str_concat runtime helper, returning its wasm function index. Subsequent calls return the same index. The bump allocator must already be declared (we re-declare it lazily here if needed since the helper calls it twice).

Signature: __str_concat(a: i32, b: i32) -> i32. Each input is a string-header pointer; the result is a freshly-allocated header pointing at a freshly-allocated byte buffer that contains the concatenation of a’s bytes followed by b’s bytes.

Implementation: allocate a.len + b.len bytes for the buffer, memory.copy each input into place, allocate an 8-byte header, store (buffer_ptr, total_len), and return the header pointer.

pub const fn str_concat_index(&self) -> Option<u32>

Wasm function index of the __str_concat helper if declared.

pub fn declare_str_len(&mut self) -> u32

Declare and emit the __str_len runtime helper, returning its wasm function index. Subsequent calls return the same index.

Signature: __str_len(s: i32) -> i32. Reads the len slot from the input’s { ptr, len } string header.

pub const fn str_len_index(&self) -> Option<u32>

Wasm function index of the __str_len helper if declared.

pub fn declare_str_is_empty(&mut self) -> u32

Declare and emit the __str_is_empty runtime helper, returning its wasm function index. Subsequent calls return the same index.

Signature: __str_is_empty(s: i32) -> i32. Loads the len slot from the input’s { ptr, len } header and returns 1 when len == 0, else 0. Backs the prelude’s extern impl String { fn is_empty(self) -> Boolean }.

pub const fn str_is_empty_index(&self) -> Option<u32>

Wasm function index of the __str_is_empty helper if declared.

pub fn declare_str_byte_at(&mut self) -> u32

Declare and emit the __str_byte_at runtime helper, returning its wasm function index. Subsequent calls return the same index.

Signature: __str_byte_at(s: i32, i: i32) -> i32. Traps via unreachable when i is out of [0, len) (the unsigned comparison covers negative i too — reinterpreted, it’s a huge u32 well past any sensible string length). Otherwise returns the byte at s.ptr + i zero-extended into i32. Backs String::byte_at and the s[i] desugaring.

pub const fn str_byte_at_index(&self) -> Option<u32>

Wasm function index of the __str_byte_at helper if declared.

pub fn declare_str_slice(&mut self) -> u32

Declare and emit the __str_slice runtime helper, returning its wasm function index. Subsequent calls return the same index. The bump allocator is declared lazily for the header allocation.

Signature: __str_slice(s: i32, start: i32, end: i32) -> i32. Returns a freshly-allocated { ptr, len } header whose ptr points into the source string’s existing backing buffer at offset start, with len = end - start. Traps via unreachable when start > end (unsigned, which also catches negative start reinterpreted as a huge u32) or when end > s.len.

Strings are immutable end-to-end so sharing the buffer is sound. Backs String::slice.

pub const fn str_slice_index(&self) -> Option<u32>

Wasm function index of the __str_slice helper if declared.

pub fn declare_str_starts_with(&mut self) -> u32

Declare and emit the __str_starts_with runtime helper, returning its wasm function index. Subsequent calls return the same index.

Signature: __str_starts_with(s: i32, prefix: i32) -> i32. Returns 1 when s begins with prefix, 0 otherwise. Empty prefix is always a match (loop body runs zero times). Implementation: short-circuits when prefix.len > s.len, then runs a byte-equality loop bounded by prefix.len. Backs String::starts_with.

pub const fn str_starts_with_index(&self) -> Option<u32>

Wasm function index of the __str_starts_with helper if declared.

pub fn declare_str_contains(&mut self) -> u32

Declare and emit the __str_contains runtime helper, returning its wasm function index. Subsequent calls return the same index.

Signature: __str_contains(s: i32, needle: i32) -> i32. Naive O(n·m) substring search. Returns 1 when needle appears in s at any offset, else 0. Empty needle is always a match (early return). Needle longer than source short-circuits to 0. Backs String::contains.

pub const fn str_contains_index(&self) -> Option<u32>

Wasm function index of the __str_contains helper if declared.

pub fn declare_array_len(&mut self) -> u32

Declare and emit the __array_len runtime helper. Reads the len field of the { ptr, len, cap } array header. Signature: __array_len(arr: i32) -> i32.

pub fn declare_array_is_empty(&mut self) -> u32

Declare and emit the __array_is_empty helper. Returns 1 when the array’s len is 0, else 0.

pub fn declare_optional_is_some(&mut self) -> u32

Declare and emit the __optional_is_some helper. Loads the 4-byte tag at offset 0; the prelude reserves crate::layout::OPTIONAL_TAG_NIL (0) for the nil/none arm so any non-zero tag indicates Some(_).

pub fn declare_optional_is_none(&mut self) -> u32

Declare and emit the __optional_is_none helper. Returns 1 when the tag at offset 0 is OPTIONAL_TAG_NIL (0).

pub fn declare_range_len(&mut self) -> u32

Declare and emit the __range_len helper for Range<I32>. Computes end - start from the two i32 fields of a Range header. Range over wider types lands in a follow-up.

pub fn declare_range_is_empty(&mut self) -> u32

Declare and emit the __range_is_empty helper for Range<I32>. Returns 1 when end <= start.

pub fn declare_dict_len(&mut self) -> u32

Declare and emit the __dict_len helper. Mirrors __array_len since the Dictionary header reuses the array { ptr, len, cap } shape.

pub fn declare_dict_is_empty(&mut self) -> u32

Declare and emit the __dict_is_empty helper.

pub fn declare_cabi_realloc(&mut self) -> u32

Declare and export cabi_realloc, the canonical-ABI hook the component runtime calls to allocate buffers in our linear memory before passing string / list<T> arguments in. The bump allocator is declared lazily if needed.

Signature: cabi_realloc(orig_ptr: i32, orig_size: i32, align: i32, new_size: i32) -> i32. Our bump allocator can’t actually resize an existing region, so we always hand back a fresh __alloc(new_size) allocation — the orig_* / align inputs are ignored. That’s correct for the canonical-ABI cases we hit today (fresh allocations during string / list lowering): the host writes the bytes into the freshly-allocated region and then hands us the (ptr, len) pair.

pub fn function_count(&self) -> u32

Total wasm function-index-space size — imports plus locally- defined functions. The wasm spec puts imports first, so this is import_function_count + functions.len().

pub fn finish(self) -> Vec<u8>

Encode the module as a sequence of bytes ready for validation or component wrapping.

Trait Implementations

impl Debug for ModuleBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ModuleBuilder

fn default() -> Self

Returns the “default value” for a type.