Crate wasmgc 

Rust-owned references to WebAssembly GC objects.

Define structs with wasmgc, allocate them with Gc, and store sequences in GcArray. Objects live in the engine’s GC heap; Rust values own the roots that keep those objects reachable. ExternRef stores host values such as JavaScript objects alongside GC references and scalars.

The runtime is intended for wasm32-unknown-unknown and wasm64-unknown-unknown. Compile the application to Wasm, then run the wasmgc post-link tool before instantiating it in an engine with WasmGC support. The tool supplies the GC instructions and reference adapters that ordinary Rust compilation cannot express directly.

Example

A cloned root observes writes to the same counter:

use wasmgc::{Gc, wasmgc};

#[wasmgc]
struct Counter {
    value: i32,
}

let counter = Gc::new(Counter { value: 1 });
let shared = counter.clone();
shared.set_value(2);
assert_eq!(counter.value(), 2);
assert!(Gc::ref_eq(&counter, &shared));

This example runs inside a post-processed Wasm module. It is not a native host program.

Ownership and storage

Moving a Gc transfers its root. Cloning allocates another root for the same object, and dropping releases that root. An object becomes collectible once no Rust root, host reference, or reachable GC object keeps it alive. This permits cyclic object graphs without reference-counted cycles.

A struct definition supplies construction values and a schema, rather than an addressable Rust payload in the GC heap. Its generated getters copy scalars or acquire owned references; setters borrow reference arguments until the write completes. There is no &T into a GC object, and managed objects do not run Rust destructors. Roots belong to their Wasm instance and cannot be sent across threads.

GcStruct describes a struct and its generated view. GcHeapObj describes either a struct or an Array heap type. GcValue defines the scalar and reference conversions used by fields, array elements, and imported or exported functions. Most applications use the macro and the built-in implementations of these traits.

Host functions

Apply wasmgc to a function to export it, or to an extern "wasmgc" block to import host functions. After post-processing, their reference parameters and results are actual Wasm references. The macro documentation covers constructors, field exports, and host contracts.

Cargo features

• alloc (enabled by default): adds conversions to and from Vec. Slice copies and GC allocations remain available without it.
• cli: enables the host-side wasmgc::process function and the wasmgc executable. It also enables std and the Wasm binary tools used by post-processing. Application dependencies normally leave it disabled.

Without cli, this crate is no_std. It does not replace the Rust allocator: Rust buffers and GC objects have separate storage and lifetimes.

Structs

Array

The heap-type description for an array of GcValue elements.

ExternRef

An owned root to a host value represented by Wasm externref.

Gc

An owned root to a struct or array on the WasmGC heap.

GcArrayIter

An iterator over values read from a borrowed GcArray.

Traits

GcHeapObj

A type describing a struct or array on the WasmGC heap.

GcStruct

Construction data and field access for a WasmGC struct.

GcValue

A value storable in GC fields and arrays and passable across Wasm boundaries.

Type Aliases

GcArray

An owned root to a fixed-length, mutable WasmGC array.

Attribute Macros

wasmgc

Defines a GC struct or a function interface for WebAssembly callers.