Trait wasmtime_runtime::GcHeap

source ·

pub unsafe trait GcHeap: 'static + Send + Sync {
Show 16 methods    // Required methods
    fn as_any(&self) -> &dyn Any;
    fn as_any_mut(&mut self) -> &mut dyn Any;
    fn enter_no_gc_scope(&mut self);
    fn exit_no_gc_scope(&mut self);
    fn header(&self, gc_ref: &VMGcRef) -> &VMGcHeader;
    fn clone_gc_ref(&mut self, gc_ref: &VMGcRef) -> VMGcRef;
    fn write_gc_ref(
        &mut self,
        host_data_table: &mut ExternRefHostDataTable,
        destination: &mut Option<VMGcRef>,
        source: Option<&VMGcRef>
    );
    fn expose_gc_ref_to_wasm(&mut self, gc_ref: VMGcRef);
    fn need_gc_before_entering_wasm(&self, num_gc_refs: NonZeroUsize) -> bool;
    fn alloc_externref(
        &mut self,
        host_data: ExternRefHostDataId
    ) -> Result<Option<VMExternRef>>;
    fn externref_host_data(
        &self,
        externref: &VMExternRef
    ) -> ExternRefHostDataId;
    fn gc<'a>(
        &'a mut self,
        roots: GcRootsIter<'a>,
        host_data_table: &'a mut ExternRefHostDataTable
    ) -> Box<dyn GarbageCollection<'a> + 'a>;
    unsafe fn vmctx_gc_heap_base(&self) -> *mut u8;
    unsafe fn vmctx_gc_heap_bound(&self) -> usize;
    unsafe fn vmctx_gc_heap_data(&self) -> *mut u8;

    // Provided method
    fn drop_gc_ref(
        &mut self,
        host_data_table: &mut ExternRefHostDataTable,
        gc_ref: VMGcRef
    ) { ... }
}

Expand description

A heap that manages garbage-collected objects.

Each wasmtime::Store is associated with a single GcHeap, and a GcHeap is only ever used with one store at a time, but GcHeaps may be reused with new stores after its original store is dropped. The reset method will be called in between each such reuse. (This reuse allows for better integration with the pooling allocator).

If a GcHeap mapped any memory, its Drop implementation should unmap that memory.

§Safety

The trait methods below are all safe: implementations of this trait must ensure that these methods cannot be misused to create memory unsafety. The expectation is that – given that VMGcRef is a newtype over an index – implementations perform similar tricks as Wasm linear memory implementations. The heap should internally be a contiguous region of memory and VMGcRef indices into the heap must be bounds checked (explicitly or implicitly via virtual memory tricks).

Furthermore, if heap corruption occurs because (for example) a VMGcRef from a different heap is used with this heap, then that corruption must be limited to within this heap. Every heap is a mini sandbox. It follows that native pointers should never be written into or read out from the GC heap, since that could spread corruption from inside the GC heap out to the native host heap. The host data for an externref, therefore, is stored in a side table (ExternRefHostDataTable) and never inside the heap. Only an id referencing a slot in that table should ever be written into the GC heap.

These constraints give us great amounts of safety compared to working with raw pointers. The worst that could happen is corruption local to heap and a panic, or perhaps reading stale heap data from a previous Wasm instance. A corrupt GcHeap can never result in the native host’s corruption.

The downside is that we are introducing heap_base + index computations and bounds checking to access GC memory, adding performance overhead. This is deemed to be a worthy trade off. Furthermore, it isn’t even a clear cut performance degradation since this allows us to use 32-bit “pointers”, giving us more compact data representations and the improved cache utilization that implies.

Trait wasmtime_runtime::GcHeapCopy item path

§Safety

Required Methods§

fn as_any(&self) -> &dyn Any

fn as_any_mut(&mut self) -> &mut dyn Any

fn enter_no_gc_scope(&mut self)

fn exit_no_gc_scope(&mut self)

fn header(&self, gc_ref: &VMGcRef) -> &VMGcHeader

fn clone_gc_ref(&mut self, gc_ref: &VMGcRef) -> VMGcRef

fn write_gc_ref( &mut self, host_data_table: &mut ExternRefHostDataTable, destination: &mut Option<VMGcRef>, source: Option<&VMGcRef> )

fn expose_gc_ref_to_wasm(&mut self, gc_ref: VMGcRef)

fn need_gc_before_entering_wasm(&self, num_gc_refs: NonZeroUsize) -> bool

fn alloc_externref( &mut self, host_data: ExternRefHostDataId ) -> Result<Option<VMExternRef>>

fn externref_host_data(&self, externref: &VMExternRef) -> ExternRefHostDataId

fn gc<'a>( &'a mut self, roots: GcRootsIter<'a>, host_data_table: &'a mut ExternRefHostDataTable ) -> Box<dyn GarbageCollection<'a> + 'a>

unsafe fn vmctx_gc_heap_base(&self) -> *mut u8

§Safety

unsafe fn vmctx_gc_heap_bound(&self) -> usize

§Safety

unsafe fn vmctx_gc_heap_data(&self) -> *mut u8

§Safety

Provided Methods§

fn drop_gc_ref( &mut self, host_data_table: &mut ExternRefHostDataTable, gc_ref: VMGcRef )

Implementors§

Trait wasmtime_runtime::GcHeap