Trait VirtualTaskManager

pub trait VirtualTaskManager:
    Debug
    + Send
    + Sync
    + 'static {
    // Required methods
    fn sleep_now(
        &self,
        time: Duration,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + Sync + 'static>>;
    fn task_shared(
        &self,
        task: Box<dyn FnOnce() -> BoxFuture<'static, ()> + Send + 'static>,
    ) -> Result<(), WasiThreadError>;
    fn task_wasm(&self, task: TaskWasm<'_, '_>) -> Result<(), WasiThreadError>;
    fn task_dedicated(
        &self,
        task: Box<dyn FnOnce() + Send + 'static>,
    ) -> Result<(), WasiThreadError>;
    fn thread_parallelism(&self) -> Result<usize, WasiThreadError>;

    // Provided methods
    fn build_memory(
        &self,
        store: &mut StoreMut<'_>,
        spawn_type: SpawnMemoryType<'_>,
    ) -> Result<Option<Memory>, WasiThreadError> { ... }
    fn spawn_with_module(
        &self,
        module: Module,
        task: Box<dyn FnOnce(Module) + Send + 'static>,
    ) -> Result<(), WasiThreadError> { ... }
}

A task executor backed by a thread pool.

Thread Safety

Due to #4158, it is possible to pass non-thread safe objects across threads by capturing them in the task passed to VirtualTaskManager::task_shared() or VirtualTaskManager::task_dedicated().

If your task needs access to a wasmer::Module, wasmer::Memory, or wasmer::Instance, it should explicitly transfer the objects using either VirtualTaskManager::task_wasm() when in syscall context or VirtualTaskManager::spawn_with_module() for higher level code.

Required Methods

fn sleep_now( &self, time: Duration, ) -> Pin<Box<dyn Future<Output = ()> + Send + Sync + 'static>>

Pause the current thread of execution.

This is typically invoked whenever a WASM thread goes idle. Besides acting as a platform-agnostic std::thread::sleep(), this also gives the runtime a chance to do asynchronous work like pumping an event loop.

fn task_shared( &self, task: Box<dyn FnOnce() -> BoxFuture<'static, ()> + Send + 'static>, ) -> Result<(), WasiThreadError>

Run an asynchronous operation on the thread pool.

This task must not block execution or it could cause deadlocks.

See the “Thread Safety” documentation on VirtualTaskManager for limitations on what a task can and can’t contain.

fn task_wasm(&self, task: TaskWasm<'_, '_>) -> Result<(), WasiThreadError>

Run a blocking WebAssembly operation on the thread pool.

This is primarily used inside the context of a syscall and allows the transfer of things like wasmer::Module across threads.

fn task_dedicated( &self, task: Box<dyn FnOnce() + Send + 'static>, ) -> Result<(), WasiThreadError>

Run a blocking operation on the thread pool.

It is okay for this task to block execution and any async futures within its scope.

fn thread_parallelism(&self) -> Result<usize, WasiThreadError>

Returns the amount of parallelism that is possible on this platform.

Provided Methods

fn build_memory( &self, store: &mut StoreMut<'_>, spawn_type: SpawnMemoryType<'_>, ) -> Result<Option<Memory>, WasiThreadError>

Build a new Webassembly memory.

May return None if the memory can just be auto-constructed.

fn spawn_with_module( &self, module: Module, task: Box<dyn FnOnce(Module) + Send + 'static>, ) -> Result<(), WasiThreadError>

Schedule a blocking task to run on the threadpool, explicitly transferring a Module to the task.

This should be preferred over VirtualTaskManager::task_dedicated() where possible because wasmer::Module is actually !Send in the browser and can only be transferred to background threads via an explicit postMessage(). See #4158 for more details.

This is very similar to VirtualTaskManager::task_wasm(), but intended for use outside of a syscall context. For example, when you are running in the browser and want to run a WebAssembly module in the background.

Implementors

impl VirtualTaskManager for TokioTaskManager

Available on crate feature sys-thread only.

impl<D, T> VirtualTaskManager for D

where D: Deref<Target = T> + Debug + Send + Sync + 'static, T: VirtualTaskManager + ?Sized,