[−][src]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 forwasmtime::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 towasmtime::Func::new
FuncExt::wrap_async
, corresponding towasmtime::Func::wrap
with callbacks that do not take awasmtime::Caller
as first argumentFuncExt::wrap_async0
toFuncExt::wrap_async15
, corresponding towasmtime::Func::wrap
with callbacks that do take awasmtime::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 towasmtime::Func::call
FuncExt::get_async
, which returns anAsyncGetter
object. TheAsyncGetter
object is just here to circumvent limitations in the Rust type system, and in particular associated existential types. OnAsyncGetter
, you can call theAsyncGetter::get0
toAsyncGetter::get15
functions just like you would have called them onwasmtime::Func
.
Modules
prelude | A “prelude” for users of the |
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 |
IntoFuncAsync | Internal trait implemented for all arguments that can be passed to
|