Struct async_fuse::Fuse

pub struct Fuse<T> { /* private fields */ }

A fusing adapter around a value.

A Fuse<T> is similar to Option<T>, with the exception that it provides and API which is more suitable for interacting with asynchronous tasks and pinned values.

For most polling operations (except Fuse::poll_inner), if the value completes, the adapter will switch to an empty state and return Poll::Pending. It can later be updated again with set.

See Fuse::new for more details.

Implementations

impl<T> Fuse<Pin<Box<T>>>

pub fn pin(value: T) -> Self

Construct a fusing adapter around a value that is already pinned.

Examples

use async_fuse::Fuse;
use std::future::Future;
use tokio::time;

async fn foo() -> u32 { 1 }

let mut fut = Fuse::pin(foo());
assert!(!fut.is_empty());

let value = (&mut fut).await;
assert!(fut.is_empty());

impl<T> Fuse<T>

pub fn new(value: T) -> Self

Construct a fusing adapter around a value.

Examples

use async_fuse::Fuse;
use std::time::Duration;
use tokio::time;

let mut sleep = Fuse::new(time::sleep(Duration::from_millis(200)));
tokio::pin!(sleep);

tokio::select! {
    _ = &mut sleep => {
        assert!(sleep.is_empty());
        sleep.set(Fuse::new(time::sleep(Duration::from_millis(200))));
    }
}

assert!(!sleep.is_empty());

Example using an unsized trait object

use async_fuse::Fuse;
use std::future::Future;
use std::pin::Pin;
use tokio::time;

async fn foo() -> u32 { 1 }
async fn bar() -> u32 { 2 }

let mut fut = Fuse::<Pin<Box<dyn Future<Output = u32>>>>::new(Box::pin(foo()));
let mut total = 0;

while !fut.is_empty() {
    let value = (&mut fut).await;

    if value == 1 {
        fut.set(Box::pin(bar()));
    }

    total += value;
}

assert_eq!(total, 3);

pub fn set(&mut self, value: T)where Self: Unpin,

Set the fused value.

Examples

use async_fuse::Fuse;
use std::time::Duration;
use tokio::time;

let mut sleep = Fuse::new(Box::pin(time::sleep(Duration::from_millis(200))));

assert!(!sleep.is_empty());
sleep.set(Box::pin(time::sleep(Duration::from_millis(200))));
assert!(!sleep.is_empty());

Example setting an unsized trait object

use async_fuse::Fuse;
use std::future::Future;
use std::pin::Pin;
use tokio::time;

async fn foo() -> u32 { 1 }
async fn bar() -> u32 { 2 }

let mut fut = Fuse::<Pin<Box<dyn Future<Output = u32>>>>::empty();
assert!(fut.is_empty());

fut.set(Box::pin(foo()));
assert!(!fut.is_empty());

fut.set(Box::pin(bar()));
assert!(!fut.is_empty());

pub fn clear(&mut self)where Self: Unpin,

Clear the fused value.

Examples

use async_fuse::Fuse;
use std::time::Duration;
use tokio::time;

let mut sleep = Fuse::new(Box::pin(time::sleep(Duration::from_millis(200))));

assert!(!sleep.is_empty());
sleep.clear();
assert!(sleep.is_empty());

pub fn empty() -> Self

Construct an empty fuse.

Examples

use async_fuse::Fuse;
use tokio::time;

let mut sleep = Fuse::<time::Sleep>::empty();
tokio::pin!(sleep);

assert!(sleep.is_empty());

pub fn is_empty(&self) -> bool

Test if the polled for value is empty.

Examples

use async_fuse::Fuse;
use std::time::Duration;
use tokio::time;

let mut sleep = Fuse::new(time::sleep(Duration::from_millis(200)));
tokio::pin!(sleep);

assert!(!sleep.is_empty());
sleep.set(Fuse::empty());
assert!(sleep.is_empty());

pub fn as_inner_ref(&self) -> Option<&T>

Access the interior value as a reference.

Examples

use async_fuse::Fuse;
use std::time::Duration;
use tokio::time;

let mut sleep = Fuse::new(time::sleep(Duration::from_millis(200)));
tokio::pin!(sleep);

assert!(sleep.as_inner_ref().is_some());
sleep.set(Fuse::empty());
assert!(sleep.as_inner_ref().is_none());

pub async fn poll_inner<P, O>(self: Pin<&mut Self>, poll: P) -> Owhere P: FnMut(Pin<&mut T>, &mut Context<'_>) -> Poll<O>,

Poll the current value with the given polling implementation.

This can be used for types which only provides a polling function.

This will never empty the underlying value.

Examples

use async_fuse::Fuse;
use std::future::Future;
use tokio::sync::mpsc;

async fn op(n: u32) -> u32 {
    n
}

let op1 = Fuse::new(op(1));
tokio::pin!(op1);

assert_eq!(op1.as_mut().poll_inner(|mut i, cx| i.poll(cx)).await, 1);
assert!(!op1.is_empty());

op1.set(Fuse::new(op(2)));
assert_eq!(op1.as_mut().poll_inner(|mut i, cx| i.poll(cx)).await, 2);
assert!(!op1.is_empty());

pub async fn poll_future<P, O>(self: Pin<&mut Self>, poll: P) -> Owhere P: FnMut(Pin<&mut T>, &mut Context<'_>) -> Poll<O>,

Poll the current value with the given polling implementation.

This can be used for types which only provides a polling function.

Once the underlying poll impl returns Poll::Ready, the underlying value will be emptied.

Examples

use async_fuse::Fuse;
use std::future::Future;
use tokio::sync::mpsc;

async fn op(n: u32) -> u32 {
    n
}

let op1 = Fuse::new(op(1));
tokio::pin!(op1);

assert_eq!(op1.as_mut().poll_future(|mut i, cx| i.poll(cx)).await, 1);
assert!(op1.is_empty());

op1.set(Fuse::new(op(2)));
assert!(!op1.is_empty());
assert_eq!(op1.as_mut().poll_future(|mut i, cx| i.poll(cx)).await, 2);
assert!(op1.is_empty());

pub async fn poll_stream<P, O>(self: Pin<&mut Self>, poll: P) -> Option<O>where P: FnMut(Pin<&mut T>, &mut Context<'_>) -> Poll<Option<O>>,

Poll the current value with the given polling implementation.

This can be used for types which only provides a polling function, or types which can be polled multiple streams. Like streams which do not provide a Stream implementation.

Will empty the fused value once the underlying poll returns Poll::Ready(None).

Examples

use async_fuse::{Fuse, Stream};
use std::future::Future;
use tokio::sync::mpsc;

fn op(n: u32) -> impl Stream<Item = u32> {
    async_stream::stream! {
        yield n;
        yield n + 1;
    }
}

let op1 = Fuse::new(op(1));
tokio::pin!(op1);

assert!(!op1.is_empty());
assert_eq!(op1.as_mut().poll_stream(|mut i, cx| i.poll_next(cx)).await, Some(1));
assert_eq!(op1.as_mut().poll_stream(|mut i, cx| i.poll_next(cx)).await, Some(2));
assert!(!op1.is_empty());
assert_eq!(op1.as_mut().poll_stream(|mut i, cx| i.poll_next(cx)).await, None);
assert!(op1.is_empty());

pub fn as_inner_mut(&mut self) -> Option<&mut T>where Self: Unpin,

Access the interior mutable value. This is only available if it implements Unpin.

Examples

use async_fuse::Fuse;

let mut rx = Fuse::new(Box::pin(async { 42 }));

assert!(rx.as_inner_mut().is_some());

pub fn as_pin_mut(&mut self) -> Pin<&mut Self>where Self: Unpin,

Helper conversion to a pinned value.

Examples

use async_fuse::Fuse;
use tokio::sync::mpsc;

let (tx, rx) = mpsc::unbounded_channel::<u32>();
let mut rx = Fuse::new(rx);

tx.send(42);

// Manually poll the sleep.
assert_eq!(rx.as_pin_mut().poll_stream(|mut i, cx| i.poll_recv(cx)).await, Some(42));

rx = Fuse::empty();
assert!(rx.is_empty());

pub async fn next(&mut self) -> Option<T::Item>where Self: Unpin, T: Stream,

Poll the next value in the stream where the underlying value is unpin.

Behaves the same as [poll_stream], except that it only works for values which are Unpin.

Examples

use async_fuse::{Fuse, Stream};
use std::future::Future;
use tokio::sync::mpsc;

fn op(n: u32) -> impl Stream<Item = u32> {
    async_stream::stream! {
        yield n;
        yield n + 1;
    }
}

let mut stream = Fuse::new(Box::pin(op(1)));
assert!(!stream.is_empty());

assert_eq!(stream.next().await, Some(1));
assert_eq!(stream.next().await, Some(2));
assert_eq!(stream.next().await, None);

assert!(stream.is_empty());

Trait Implementations

impl<T> Default for Fuse<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T> From<Box<T, Global>> for Fuse<Pin<Box<T>>>

fn from(value: Box<T>) -> Self

Converts to this type from the input type.

impl<T> From<Option<Box<T, Global>>> for Fuse<Pin<Box<T>>>

fn from(value: Option<Box<T>>) -> Self

Converts to this type from the input type.

impl<T> From<Option<T>> for Fuse<T>

fn from(value: Option<T>) -> Self

Converts to this type from the input type.

impl<T> Future for Fuse<T>where T: Future,

type Output = <T as Future>::Output

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempt to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.

impl<T> Stream for Fuse<T>where T: Stream,

type Item = <T as Stream>::Item

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.