async-fuse
Helpers for "fusing" asynchronous computations.
A fused operation has a well-defined behavior once the operation has completed. For Fuse it means that an operation that has completed will block forever by returning Poll::Pending.
This is similar to the Fuse type provided in futures-rs, but provides more utility allowing it to interact with types which does not implement FusedFuture or FusedStream as is now the case with all Tokio types since 1.0.
We also use Fuse to represent optional values, just like [Option]. But Fuse provides implementations and functions which allow us to safely perform operations over the value when it's pinned. Exactly what's needed to drive a Stream (see next) or poll a Future that might or might not be set.
Features
Simplifying tokio::select
One of the main uses for Fuse is to simplify how we use tokio::select. In this section we'll look at how we can improve an optional branch, where the future being polled might or might not be set.
let mut maybe_future = Some;
pin!;
select!
assert!;
The async
block above is necessary because the future is polled eagerly
regardless of the branch precondition. This would cause the unwrap
to
panic in case the future isn't set. We also need to explicitly set the pin
to None
after completion. Otherwise we might poll it later which might
panic.
With Fuse we can rewrite the branch and remove the async
block. It also
unsets the future for us after completion.
use Fuse;
let mut maybe_future = new;
pin!;
select!
assert!;
Finally if we don't need the else branch to evalute we can skip the branch precondition entirely. Allowing us to further reduce the code.
use Fuse;
let mut maybe_future = new;
pin!;
select!
assert!;
Fusing on the stack
For the first example we'll be fusing the value on the stack using tokio::pin. We'll also be updating the fuse as it completes with another sleep with a configurable delay. Mimicking the behavior of Interval.
This is available as the
stack_ticker
example:
use Fuse;
use Duration;
use time;
let mut duration = from_millis;
let sleep = new;
pin!;
let update_duration = new;
pin!;
for _ in 0..10usize
Fusing on the heap
For some types it might be easier to fuse the value on the heap. To make this easier, we provide the Fuse::pin constructor which provides a fused value which is pinned on the heap.
As a result, it looks pretty similar to the above example.
This is available as the
heap_ticker
example:
use Fuse;
use Duration;
use time;
let mut duration = from_millis;
let mut sleep = pin;
let mut update_duration = pin;
for _ in 0..10usize
Fusing trait objects
The following showcases how we can fuse a trait object. Trait objects are useful since they allow the fused value to change between distinct implementations. The price is that we perform dynamic dispatch which has a small cost.
Also note that because CoerceUnsized is not yet stable, we cannot use Fuse::pin for convenience and have to pass a pinned box through Fuse::new.
This is available as the
trait_object_ticker
example:
use Fuse;
use Future;
use Pin;
use Duration;
use time;
let mut duration = from_millis;
let mut sleep: =
new;
let mut update_duration: =
new;
for _ in 0..10usize
License: MIT/Apache-2.0