Struct async_fuse::Fuse

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

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.

For most polling operations except Fuse::poll_inner, if the value completes, the adapter will switch to an empty state and return Poll::Pending until 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) -> O where
    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) -> O where
    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>

pub fn default() -> Self

Returns the "default value" for a type.

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

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

Performs the conversion.

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

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

Performs the conversion.

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

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

Performs the conversion.

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

type Output = T::Output

The type of value produced on completion.

pub 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::Item

Values yielded by the stream.

pub 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.

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

Returns the bounds on the remaining length of the stream.