Trait sp_wasm_interface::FunctionContext

source · [−]

pub trait FunctionContext {
    fn read_memory_into(
        &self, 
        address: Pointer<u8>, 
        dest: &mut [u8]
    ) -> Result<()>;
    fn write_memory(&mut self, address: Pointer<u8>, data: &[u8]) -> Result<()>;
    fn allocate_memory(&mut self, size: WordSize) -> Result<Pointer<u8>>;
    fn deallocate_memory(&mut self, ptr: Pointer<u8>) -> Result<()>;
    fn sandbox(&mut self) -> &mut dyn Sandbox;
    fn register_panic_error_message(&mut self, message: &str);

    fn read_memory(
        &self, 
        address: Pointer<u8>, 
        size: WordSize
    ) -> Result<Vec<u8>> { ... }
}

Expand description

Context used by Function to interact with the allocator and the memory of the wasm instance.

Required methods

source

fn read_memory_into(&self, address: Pointer<u8>, dest: &mut [u8 ]) -> Result<()>

Read memory into the given dest buffer from address.

source

fn write_memory(&mut self, address: Pointer<u8>, data: &[u8 ]) -> Result<()>

Write the given data at address into the memory.

source

fn allocate_memory(&mut self, size: WordSize) -> Result<Pointer<u8>>

Allocate a memory instance of size bytes.

source

fn deallocate_memory(&mut self, ptr: Pointer<u8>) -> Result<()>

Deallocate a given memory instance.

source

fn sandbox(&mut self) -> &mut dyn Sandbox

Provides access to the sandbox.

source

fn register_panic_error_message(&mut self, message: &str)

Registers a panic error message within the executor.

This is meant to be used in situations where the runtime encounters an unrecoverable error and intends to panic.

Panicking in WASM is done through the unreachable instruction which causes an unconditional trap and immediately aborts the execution. It does not however allow for any diagnostics to be passed through to the host, so while we do know that something went wrong we don’t have any direct indication of what exactly went wrong.

As a workaround we use this method right before the execution is actually aborted to pass an error message to the host so that it can associate it with the next trap, and return that to the caller.

A WASM trap should be triggered immediately after calling this method; otherwise the error message might be associated with a completely unrelated trap.

It should only be called once, however calling it more than once is harmless and will overwrite the previously set error message.