Crate wasmtime_async

wasmtime-async

This crate is an extension to the wasmtime crate. It makes it possible to use wasmtime along with futures, without having to consider every WebAssembly call as blocking. Note however that it is designed only for cases where the time spent in WebAssembly is indeed not enough to warrant running it in a worker thread -- it is designed with, in mind, relatively lightweight WebAssembly code that then calls into async callbacks provided from the rust side.

The WebAssembly code will be run on a specific stack and, when it calls an async callback provided by rust, will be interrupted until the future has returned. As such, so long as the time spent inside WebAssembly is not enough to warrant in itself running the whole task on a blocking executor, it should be possible to run WebAssembly code that integrates seamlessly with async code.

The drawback of this approach is that the async callbacks appear as though they were blocking to WebAssembly. This is unfortunately necessary to not require the WebAssembly code itself to be async-ready.

Usage

This crate provides two main elements:

• The Stack struct, that owns a stack on which WebAssembly code can run
• The FuncExt trait, that provides extension methods for wasmtime::Func for dealing with asynchronous callbacks provided by Rust to WebAssembly.

Stack

The Stack struct is easy to use: just use Stack::new, and it will create a stack on which WebAssembly code can run.

Running code on a Stack takes a mutable reference to it so long as the code is running, thus preventing multiple functions from using the same stack without any runtime cost or unsafe usage.

FuncExt

The FuncExt provides most of the interesting methods in this crate.

Wrapping async functions for use from WebAssembly

First, use the methods to wrap async functions in Rust so that they could be used transparently from WebAssembly:

• FuncExt::new_async, corresponding to wasmtime::Func::new
• FuncExt::wrap_async, corresponding to wasmtime::Func::wrap with callbacks that do not take a wasmtime::Caller as first argument
• FuncExt::wrap_async0 to FuncExt::wrap_async15, corresponding to wasmtime::Func::wrap with callbacks that do take a wasmtime::Caller as first argument

It would be better to have a single FuncExt::wrap_async function, but unfortunately, due to both orphan rules and a probable limitation of rustc, it is not possible to do so at the moment, hence the multiple methods that handle each part of Func::wrap.

Calling WebAssembly that uses async functions

When calling into WebAssembly code that potentially uses async functions, you must use an async-ready calling function, or a panic will arise!

The functions are these:

• FuncExt::call_async, corresponding to wasmtime::Func::call
• FuncExt::get_async, which returns an AsyncGetter object. The AsyncGetter object is just here to circumvent limitations in the Rust type system, and in particular associated existential types. On AsyncGetter, you can call the AsyncGetter::get0 to AsyncGetter::get15 functions just like you would have called them on wasmtime::Func.

Modules

prelude

A “prelude” for users of the wasmtime-async crate.

Structs

AsyncGetter	Helper struct for retrieving native functions out of WebAssembly functions that call async callbacks.
Stack	A stack on which to run WebAssembly code
WasmFuture	Future that runs WebAssembly code to completion, when the WebAssembly potentially includes async callback calls.

Traits

FuncExt	The extension trait to wasmtime::Func, that holds most of the interest of this crate.
IntoFuncAsync	Internal trait implemented for all arguments that can be passed to FuncExt::wrap_async.