Trait ResourceLimiter

Source

pub trait ResourceLimiter {
    // Required methods
    fn memory_growing(
        &mut self,
        current: usize,
        desired: usize,
        maximum: Option<usize>,
    ) -> Result<bool, LimiterError>;
    fn table_growing(
        &mut self,
        current: usize,
        desired: usize,
        maximum: Option<usize>,
    ) -> Result<bool, LimiterError>;
    fn instances(&self) -> usize;
    fn tables(&self) -> usize;
    fn memories(&self) -> usize;

    // Provided methods
    fn memory_grow_failed(&mut self, _error: &LimiterError) { ... }
    fn table_grow_failed(&mut self, _error: &LimiterError) { ... }
}

Expand description

Used by hosts to limit resource consumption of instances.

Resources limited via this trait are primarily related to memory.

Note that this trait does not limit 100% of memory allocated. Implementers might still allocate memory to track data structures and additionally embedder-specific memory allocations are not tracked via this trait.

Required Methods§

Source

fn memory_growing( &mut self, current: usize, desired: usize, maximum: Option<usize>, ) -> Result<bool, LimiterError>

Notifies the resource limiter that an instance’s linear memory has been requested to grow.

current is the current size of the linear memory in bytes.
desired is the desired size of the linear memory in bytes.
maximum is either the linear memory’s maximum or a maximum from an instance allocator, also in bytes. A value of None indicates that the linear memory is unbounded.

The current and desired amounts are guaranteed to always be multiples of the WebAssembly page size, 64KiB.

§Return Value

If Ok(true) is returned from this function then the growth operation is allowed. This means that the wasm memory.grow or table.grow instructions will return with the desired size, in wasm pages. Note that even if Ok(true) is returned, though, if desired exceeds maximum then the growth operation will still fail.

If Ok(false) is returned then this will cause the grow instruction in a module to return -1 (failure), or in the case of an embedder API calling any of the below methods an error will be returned.

§Errors

If Err(e) is returned then the memory.grow or table.grow functions will behave as if a trap has been raised. Note that this is not necessarily compliant with the WebAssembly specification but it can be a handy and useful tool to get a precise backtrace at “what requested so much memory to cause a growth failure?”.

Source

fn table_growing( &mut self, current: usize, desired: usize, maximum: Option<usize>, ) -> Result<bool, LimiterError>

Notifies the resource limiter that an instance’s table has been requested to grow.

current is the current number of elements in the table.
desired is the desired number of elements in the table.
maximum is either the table’s maximum or a maximum from an instance allocator. A value of None indicates that the table is unbounded.