async_rs/lib.rs
1#![deny(missing_docs, missing_debug_implementations, unsafe_code)]
2#![warn(unreachable_pub, unused_qualifications, unused_lifetimes)]
3#![warn(
4 clippy::must_use_candidate,
5 clippy::unwrap_in_result,
6 clippy::panic_in_result_fn
7)]
8#![allow(clippy::manual_async_fn)]
9
10//! A Rust async runtime abstraction library.
11//!
12//! Provides a unified [`Runtime`] type and a set of [`traits`]
13//! (`Executor`, `Reactor`, `Dns`, …) that abstract over Tokio, smol, and
14//! async-global-executor. Applications select exactly one runtime via feature
15//! flags; library crates depend on the trait objects and remain
16//! runtime-agnostic.
17//!
18//! # Feature flags
19//!
20//! | Flag | Notes |
21//! |------|-------|
22//! | `tokio` *(default)* | Tokio runtime |
23//! | `smol` | smol executor |
24//! | `async-global-executor` | async-global-executor |
25//! | `async-io` | async-io reactor (required by `smol`) |
26//! | `hickory-dns` | Hickory DNS resolver (tokio only) |
27//!
28//! # Example
29//!
30//! ```rust
31//! # #[cfg(feature="tokio")]
32//! # {
33//! use async_rs::{Runtime, TokioRuntime, traits::*};
34//! use std::{io, time::Duration};
35//!
36//! async fn get_a(rt: &TokioRuntime) -> io::Result<u32> {
37//! rt.spawn_blocking(|| Ok(12)).await
38//! }
39//!
40//! async fn get_b(rt: &TokioRuntime) -> io::Result<u32> {
41//! rt.spawn(async { Ok(30) }).await
42//! }
43//!
44//! async fn tokio_main(rt: &TokioRuntime) -> io::Result<()> {
45//! let a = get_a(rt).await?;
46//! let b = get_b(rt).await?;
47//! rt.sleep(Duration::from_millis(500)).await;
48//! assert_eq!(a + b, 42);
49//! Ok(())
50//! }
51//!
52//! fn main() -> io::Result<()> {
53//! let rt = Runtime::tokio()?;
54//! rt.block_on(tokio_main(&rt))
55//! }
56//! # }
57//! ```
58//!
59//! Note that the `io::Result` above is the *task's own* output: awaiting a
60//! [`Task`](util::Task) leaves no room to report that the task itself failed,
61//! so a task which panicked resumes its panic in the awaiting task, and
62//! awaiting one which was canceled, or whose runtime went away, panics too.
63
64mod runtime;
65pub use runtime::*;
66
67pub mod traits;
68
69mod implementors;
70pub use implementors::*;
71
72pub mod util;
73
74mod sys;