Enum Collector

#[non_exhaustive]
pub enum Collector {
    Auto,
    DeferredReferenceCounting,
    Null,
}

Possible garbage collector implementations for Wasm.

This is used as an argument to the Config::collector method.

The properties of Wasmtime’s available collectors are summarized in the following table:

Collector	Collects Garbage1	Latency2	Throughput3	Allocation Speed4	Heap Utilization5
DeferredReferenceCounting	Yes, but not cycles	🙂	🙁	😐	😐
Null	No	🙂	🙂	🙂	🙂

---

1. Whether or not the collector is capable of collecting garbage and cyclic garbage. ↩

2. How long the Wasm program is paused during garbage collections. Shorter is better. In general, better latency implies worse throughput and vice versa. ↩

3. How fast the Wasm program runs when using this collector. Roughly equivalent to the number of Wasm instructions executed per second. Faster is better. In general, better throughput implies worse latency and vice versa. ↩

4. How fast can individual objects be allocated? ↩

5. How many objects can the collector fit into N bytes of memory? That is, how much space for bookkeeping and metadata does this collector require? Less space taken up by metadata means more space for additional objects. Reference counts are larger than mark bits and free lists are larger than bump pointers, for example. ↩

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Auto

An indicator that the garbage collector should be automatically selected.

This is generally what you want for most projects and indicates that the wasmtime crate itself should make the decision about what the best collector for a wasm module is.

Currently this always defaults to the deferred reference-counting collector, but the default value may change over time.

DeferredReferenceCounting

The deferred reference-counting collector.

A reference-counting collector, generally trading improved latency for worsened throughput. However, to avoid the largest overheads of reference counting, it avoids manipulating reference counts for Wasm objects on the stack. Instead, it will hold a reference count for an over-approximation of all objects that are currently on the stack, trace the stack during collection to find the precise set of on-stack roots, and decrement the reference count of any object that was in the over-approximation but not the precise set. This improves throughtput, compared to “pure” reference counting, by performing many fewer refcount-increment and -decrement operations. The cost is the increased latency associated with tracing the stack.

This collector cannot currently collect cycles; they will leak until the GC heap’s store is dropped.

Null

The null collector.

This collector does not actually collect any garbage. It simply allocates objects until it runs out of memory, at which point further objects allocation attempts will trap.

This collector is useful for incredibly short-running Wasm instances where additionally you would rather halt an over-allocating Wasm program than spend time collecting its garbage to allow it to keep running. It is also useful for measuring the overheads associated with other collectors, as this collector imposes as close to zero throughput and latency overhead as possible.

Trait Implementations

impl Clone for Collector

fn clone(&self) -> Collector

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Collector

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

Formats the value using the given formatter.

impl Default for Collector

fn default() -> Collector

Returns the “default value” for a type.

impl PartialEq for Collector

fn eq(&self, other: &Collector) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for Collector

impl Eq for Collector

impl StructuralPartialEq for Collector