async_select/
lib.rs

1#![no_std]
2
3/// # Select multiplex asynchronous futures simultaneously
4///
5/// `select!` supports three different clauses:
6///
7/// * pattern = future [, if condition] => code,
8/// * default => code,
9/// * complete => code,
10///
11/// ## Evaluation order
12/// * All conditions and futures are evaluated before selection.
13/// * Future expression is not evaluated if corresponding condition evaluated to false.
14/// * Whenever a branch is ready, its clause is executed. And the whole select returns.
15/// * Fail to match a refutable pattern will disable that branch.
16/// * `default` clause is executed if no futures are ready. That is non blocking mode.
17/// * If all branches are disabled by conditions or refutable pattern match, it resort to
18///   `complete` or `default` in case of no `complete`.
19///
20/// ## Panics
21/// * Panic when all futures are disabled or completed and there is no `default` or `complete`.
22///
23/// ## Comparing with `tokio::select!`
24/// * Future expression is only evaluated if condition meets.
25///   ```
26///   use std::future::ready;
27///   use async_select::select;
28///
29///   async fn guard_future_by_condition() {
30///       let opt: Option<i32> = None;
31///       let r = select! {
32///           v = ready(opt.unwrap()), if opt.is_some() => v,
33///           v = ready(6) => v,
34///       };
35///       assert_eq!(r, 6);
36///   }
37///   ```
38///   This will panic in `tokio::select!` as it evaluates `ready(opt.unwrap())` irrespective of
39///   corresponding condition. See <https://github.com/tokio-rs/tokio/pull/6555>.
40/// * There is no `default` counterpart in `tokio::select!`. But it could be emulated with `biased`
41///   and `ready(())`.`complete` is same as `else` in `tokio::select!`.
42/// * `async_select::select!` depends only on `proc_macro` macros and hence the generated code is
43///   `no_std` compatible.
44///
45/// ## Polling order
46/// By default, the polling order of each branch is indeterminate. Use `biased;` to poll
47/// sequentially if desired.
48/// ```
49/// use async_select::select;
50/// use core::future::{pending, ready};
51///
52/// async fn poll_sequentially() {
53///     let r = select! {
54///         biased;
55///         default => unreachable!(),
56///         _ = pending() => unreachable!(),
57///         _ = pending() => unreachable!(),
58///         v = ready(5) => v,
59///         v = ready(6) => v,
60///         v = ready(7) => v,
61///     };
62///     assert_eq!(r, 5);
63/// }
64/// ```
65///
66/// ## Efficiency
67/// `select!` blindly `Future:poll` all enabled futures without checking for waking branch.
68///
69/// ## Examples
70/// ```rust
71/// use async_select::select;
72/// use core::future::{pending, ready};
73///
74/// async fn on_ready() {
75///     let r = select! {
76///         _ = pending() => unreachable!(),
77///         v = ready(5) => v,
78///         default => unreachable!(),
79///     };
80///     assert_eq!(r, 5);
81/// }
82/// ```
83#[macro_export]
84macro_rules! select {
85    (biased; $($token:tt)*) => {
86        $crate::select_biased! { $($token)* }
87    };
88    ($($token:tt)*) => {
89        $crate::select_default! { $($token)* }
90    };
91}
92
93// By importing them into this crate and using `$crate::select_xyz`, caller crates
94// are free from depending on `async-select-proc-macros` directly.
95#[doc(hidden)]
96pub use async_select_proc_macros::select_biased;
97#[doc(hidden)]
98pub use async_select_proc_macros::select_default;
async_select/lib.rs

async_select/
lib.rs
