Struct wasmtime_wasi::preview2::Table

pub struct Table { /* private fields */ }

The Table type is designed to map u32 handles to resources. The table is now part of the public interface to a WasiCtx - it is reference counted so that it can be shared beyond a WasiCtx with other WASI proposals (e.g. wasi-crypto and wasi-nn) to manage their resources. Elements in the Table are Any typed.

The Table type is intended to model how the Interface Types concept of Resources is shaping up. Right now it is just an approximation.

Implementations

impl Table

pub fn new() -> Self

Create an empty table

pub fn push( &mut self, entry: Box<dyn Any + Send + Sync> ) -> Result<u32, TableError>

Insert a resource at the next available index.

pub fn push_child( &mut self, entry: Box<dyn Any + Send + Sync>, parent: u32 ) -> Result<u32, TableError>

Insert a resource at the next available index, and track that it has a parent resource.

The parent must exist to create a child. All children resources must be destroyed before a parent can be destroyed - otherwise Table::delete or OccupiedEntry::remove_entry will fail with TableError::HasChildren.

Parent-child relationships are tracked inside the table to ensure that a parent resource is not deleted while it has live children. This allows child resources to hold “references” to a parent by table index, to avoid needing e.g. an Arc<Mutex<parent>> and the associated locking overhead and design issues, such as child existence extending lifetime of parent referent even after parent resource is destroyed, possibility for deadlocks.

Parent-child relationships may not be modified once created. There is no way to observe these relationships through the Table methods except for erroring on deletion, or the std::fmt::Debug impl.

pub fn contains_key(&self, key: u32) -> bool

Check if the table has a resource at the given index.

pub fn is<T: Any + Sized>(&self, key: u32) -> bool

Check if the resource at a given index can be downcast to a given type. Note: this will always fail if the resource is already borrowed.

pub fn get<T: Any + Sized>(&self, key: u32) -> Result<&T, TableError>

Get an immutable reference to a resource of a given type at a given index. Multiple immutable references can be borrowed at any given time. Borrow failure results in a trapping error.

pub fn get_mut<T: Any + Sized>( &mut self, key: u32 ) -> Result<&mut T, TableError>

Get a mutable reference to a resource of a given type at a given index. Only one mutable reference can be borrowed at any given time. Borrow failure results in a trapping error.

pub fn entry(&mut self, index: u32) -> Result<OccupiedEntry<'_>, TableError>

Get an OccupiedEntry corresponding to a table entry, if it exists. This allows you to remove or replace the entry based on its contents. The methods available are a subset of std::collections::hash_map::OccupiedEntry - it does not give access to the key, it restricts replacing the entry to items of the same type, and it does not allow for deletion.

pub fn delete<T: Any + Sized>(&mut self, key: u32) -> Result<T, TableError>

Remove a resource at a given index from the table.

If this method fails, the resource remains in the table.

May fail with TableError::HasChildren if the resource has any live children.

pub fn iter_entries<'a, T>( &'a mut self, map: HashMap<u32, T> ) -> impl Iterator<Item = (Result<&'a mut dyn Any, TableError>, T)>

Zip the values of the map with mutable references to table entries corresponding to each key. As the keys in the HashMap are unique, this iterator can give mutable references with the same lifetime as the mutable reference to the Table.

Trait Implementations

impl Debug for Table

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

Formats the value using the given formatter.

impl TablePollableExt for Table

fn push_host_pollable(&mut self, p: HostPollable) -> Result<u32, TableError>

fn get_host_pollable_mut( &mut self, fd: u32 ) -> Result<&mut HostPollable, TableError>

fn delete_host_pollable(&mut self, fd: u32) -> Result<HostPollable, TableError>

impl TableStreamExt for Table

fn push_input_stream( &mut self, istream: Box<dyn HostInputStream> ) -> Result<u32, TableError>

Push a HostInputStream into a Table, returning the table index.

fn get_input_stream_mut( &mut self, fd: u32 ) -> Result<&mut dyn HostInputStream, TableError>

Get a mutable reference to a HostInputStream in a Table.

fn delete_input_stream( &mut self, fd: u32 ) -> Result<Box<dyn HostInputStream>, TableError>

Remove HostInputStream from table:

fn push_output_stream( &mut self, ostream: Box<dyn HostOutputStream> ) -> Result<u32, TableError>

Push a HostOutputStream into a Table, returning the table index.

fn get_output_stream_mut( &mut self, fd: u32 ) -> Result<&mut dyn HostOutputStream, TableError>

Get a mutable reference to a HostOutputStream in a Table.

fn delete_output_stream( &mut self, fd: u32 ) -> Result<Box<dyn HostOutputStream>, TableError>

Remove HostOutputStream from table: