Crate safina_executor

An async executor.

It is part of safina, a safe async runtime.

Features

• Spawn async tasks to execute on a threadpool.
• Schedule closures or FnOnce to run on a separate thread pool for blocking jobs.
• Supports multiple executors.
• forbid(unsafe_code)
• Depends only on std
• Good test coverage (100%)

Limitations

• Allocates memory
• Not optimized

Documentation

https://docs.rs/safina-executor

Examples

let executor = safina_executor::Executor::default();
let (sender, receiver) = std::sync::mpsc::channel();
executor.spawn(async move {
    sender.send(()).unwrap();
});
receiver.recv().unwrap();

let result = safina_executor::block_on(async {
    prepare_request().await?;
    execute_request().await
})?;

let result = safina_executor::schedule_blocking(|| {
    read_file1()?;
    read_file2()
}).await?;

Alternatives

• async-executor
  • Popular
  • Dependencies have some unsafe code
• futures-executor
  • Very popular
  • Full of unsafe
• tokio-executor
  • Very popular
  • Fast
  • Internally complicated
  • Full of unsafe
• executors
  • Dependencies have lots of unsafe code
• bastion-executor
  • Lots of unsafe code
• rayon_core
  • Generous amounts of unsafe code
• pollster
  • Minimal
  • Has a little unsafe code
• lelet
  • Automatically scales worker thread pool
  • Lots of unsafe code
• fibers
  • Dependencies are full of unsafe
• nostd_async
  • Has some unsafe code
• embedded-executor
  • Generous amounts of unsafe code
• spin_on
  • Minimal
• pasts
• switchyard
  • Lots of unsafe code
• sealrs
• rusty_pool
  • Automatically adjusts thread pool
  • Dependencies are full of unsafe

Changelog

• v0.2.0
  • Executor::new and Executor::with_name to return Result.
  • Upgrade to safina-threadpool v0.2.0.
• v0.1.7 - block_on functions to take futures that are not Send.
• v0.1.6 - Fix deadlock in block_on and block_on_unpin when task is awakened a second time.
• v0.1.5 - Support stable Rust! Needs 1.51+.
• v0.1.4 - Add schedule_blocking and Executor::schedule_blocking
• v0.1.3
  • Removed global executor. Users must explicitly create executor.
  • Removed dependency on unstable OnceCell.
  • Uses safina_threadpool internally.
• v0.1.2 - Let callers pass futures to spawn and block_on without using Box::pin. Add spawn_unpin and block_on_unpin for folks who need to avoid allocating. so callers don’t have to.
• v0.1.1 - Fix badge and update readme
• v0.1.0 - Renamed from safina

TO DO

• DONE - Implement spawn
• DONE - Implement block_on
• DONE - Implement increase_threads_to
• DONE - Drop finished futures
• DONE - Handle task panic
• DONE - Add stop_threads, allow_threads, and increase_threads_to.
• DONE - Add tests
• DONE - Add docs
• DONE - Publish on crates.io
• DONE - Add an #[async_test] macro
• DONE - Build with Rust stable.
• Add a stress test
• Add a benchmark. See benchmarks in https://crates.io/crates/executors
• Add an #[async_main] macro
• Look into using flume to eliminate the receiver mutex and reduce contention.

Release Process

1. Edit Cargo.toml and bump version number.
2. Run ./release.sh

Structs

Executor

A collection of threads for executing tasks and blocking jobs.

ThreadExecutorGuard

Guard returned by set_thread_executor.

Functions

block_on

Executes the future on the current thread and returns its result.

block_on_unpin

Executes the future on the current thread and returns its result.

get_thread_executor

Gets the Executor from thread-local storage.

schedule_blocking

Schedules f to run on any available thread in the blocking thread pool.

set_thread_executor

Sets executor as the Executor for the current thread, saving it to thread-local storage.

spawn

Creates a new task to execute fut and schedules it for immediate execution.

spawn_unpin

Creates a new task to execute fut and schedules it for immediate execution.