wasm-rs-async-executor

Crates.iowasm-rs-async-executor
lib.rswasm-rs-async-executor
version0.9.0
sourcesrc
created_at2021-02-05 22:45:54.300195
updated_at2021-02-21 22:03:22.544133
descriptionAsync executor for WebAssembly
homepage
repositoryhttps://github.com/wasm-rs/async-executor
max_upload_size
id351342
size55,297
Yurii Rashkovskii (yrashk)

documentation

https://docs.rs/wasm-rs-async-executor

README

Async Executor for WebAssembly

Crate API Chat

There are a number of async task executors available in Rust's ecosystem. However, most (if not all?) of them rely on primitives that might not be available or optimal for WebAssembly deployment at the time.

Usage

Include this dependency in your Cargo.toml:

[dependencies]
wasm-rs-async-executor = "0.9.0"

wasm-rs-async-executor is expected to work on stable Rust, 1.49.0 and higher up. It may also work on earlier versions. This hasn't been tested yet.

Supported targets

Currently, it's been only tested on wasm32-unknown-unknown and, excluding cooperative functionality, it passes tests under wasmtime and wasmer with wasm32-wasi target. Further testing is to be completed.

Notes

Please note that this library hasn't received much analysis in terms of safety and soundness. Some of the caveats related to that might never be resolved completely. This is an ongoing development and the maintainer is aware of potential pitfalls. Any productive reports of unsafeties or unsoundness are welcomed (whether they can be resolved or simply walled with unsafe for end-user to note).

FAQ

Q: Why not just use wasm-bindgen-futures?

A: (short) In many cases, wasm-bindgen-futures is just fine

A: (longer) There are some subtle differences in the way wasm-rs-async-executor exposes its functionality. The core idea behind it is to expose a reasonable amount of explicit controls over the its operations. You need to run the executor explicitly, you can block on futures (again, explicitly -- which gives you a limited ability to do scoped futures). It does come with minor trade-offs. For example, if you want to use async APIs from your host environment, you can't simply await on then, as the executor won't yield to the browser until told to do so. However, this is typically solved by simply running a permanent task that loops yielding to the browser.

Ultimately, if this amount of control is beneficial for your case, then perhaps this executor is waranted. It is also important to note that currently wasm-rs-async-executor does not support WebAssembly multi-threading in any way. wasm-bindgen-futures does, if the standard library is built with support for it. It is planned to support this, but hasn't been high priority so far due to current state of things in Rust.

License

Licensed under either of

Commit count: 96

cargo fmt