Crate enfync

Environment-friendly async

Ergonomic utilities for async IO work that easily cross-compiles for native and browser.

• Use enfync::builtin::Handle::spawn() to launch an environment-agnostic IO task. The returned enfync::PendingResult<R> can be used as a join handle on the task. Any task errors encountered during your async work will be discarded and replaced with [enfync::ResultError::TaskFailure`].

This crate is designed for projects that want to ergonomically support WASM targets without sacrificing performance on native builds. To achieve that goal, the API is constrained to the greatest common denominator between native/browser async capabilities. In particular, there is no built-in mechanism for aborting a task, and enfync::blocking utilities are restricted to non-WASM builds.

Features

• default: builtin
• builtin: Enables the enfync::builtin module. The handle enfync::builtin::Handle is an alias for platform-specific implementations of the enfync::Handle trait (tokio on non-WASM, wasm-bindgen-futures on WASM).

Important notes

• In WASM, only one task can run at a time. The first ‘task’ is always fn main(), followed by whatever tasks were spawned during fn main(). Any long-running task, including fn main(), will block all other tasks. This means you fundamentally cannot benefit from this crate unless you develop your project from the ground up with WASM in mind.
• We do not provide any API dealing with ‘web workers’, which are a browser feature similar to threads except they have a huge overhead to launch and interact with.

Recommended WASM Build

We provide a custom release-wasm profile that enables panic = "abort" and optimizes for small binaries. There is a corresponding dev-wasm profile that enables panic = "abort". Currently wasm-pack doesn’t support custom profiles, so we have to settle for a more verbose build script that overwrites the build files.

1. Prep tooling

• rustup target install wasm32-unknown-unknown
• cargo install wasm-pack
• install wasm-opt

2. Build (this builds twice because we want the wasm-pack convenience output and the release-wasm profile; you can drop the wasm-pack piece as needed)

wasm-pack build --target no-modules --mode no-install &&
cargo build --profile=release-wasm --target wasm32-unknown-unknown &&
wasm-bindgen --out-dir ./pkg --target no-modules ./target/wasm32-unknown-unknown/release-wasm/enfync.wasm

3. Optimize WASM binary

• wasm-opt -Os pkg/enfync_bg.wasm -o pkg/enfync_bg.wasm
• See the rustwasm reference for further optimizations.

4. Compress WASM binary

• TODO: gzip

Running WASM

• Tests: wasm-pack test --firefox --headless. Note that --node tests currently fail due to an obscure error caused by the wasmtimer dependency.
• Run your program locally: wasm-server-runner tool

Options

• TOKIO_WORKER_THREADS (env variable): Size of default IO task pool (native builds only).

Perf Notes

• Default threadpool initialization for enfync::builtin::native::TokioHandle::default() is deferred to the first time you make a default handle.

Comparison with prokio

Pros

• Can await enfync::PendingResult<R>::extract() as a join handle.
• enfync::builtin::native::TokioHandle::try_adopt() can adopt an existing normal tokio runtime (no dependency on prokio’s LocalSet-specific design).
• The enfync::ResultReceiver/enfync::Handle abstractions allow users to easily implement their own custom runtimes (you could even implement a prokio-backed Handle).

Cons

• prokio is more developed, with a runtime builder, pinned task synchronization primitives, etc.
• prokio is compatible with ?Send tasks, whereas enfync only allows Send tasks. That means prokio is better than enfync for projects that need to pass WebAssembly types between tasks.

Modules

• blocking
• builtin

Structs

• ImmedateResultReceiver
  Result receiver with an immediately-available result.
• OneshotResultReceiver
  Uses a oneshot to receive the result.
• PendingResult
  The pending result of async work.
• SimpleResultReceiver
  Uses a future to receive the result.

Enums

• ResultError
  Error that can be emitted by a PendingResult.

Traits

• AdoptOrDefault
  Try to adopt the existing runtime, otherwise fall back to the default runtime.
• Handle
  A handle to a runtime.
• OneshotSpawner
  Task spawner for OneshotResultReceiver.
• ResultReceiver
  Represents a result receiver for async tasks. See PendingResult::new().
• SimpleSpawner
  Task spawner for SimpleResultReceiver.
• TryAdopt
  Try to adopt the existing runtime.

Functions

• sleep
  Sleep for the specified duration.