Trait foreback::FutureExt

pub trait FutureExt: Sized + Future {
    #[must_use = "futures do nothing unless you `.await` or poll them"]
    fn with_background<B>(self, background: B) -> ForegroundBackground<Self, B>
    where
        B: Future<Output = ()> + FusedFuture,
    { ... }
    #[must_use = "futures do nothing unless you `.await` or poll them"]
    fn with_try_background<B, E>(
        self, 
        background: B
    ) -> TryForegroundBackground<Self, B>
    where
        B: Future<Output = Result<(), E>>,
    { ... }
}

Extension trait for Future providing adapters to run other futures concurrently in the background.

Provided methods

#[must_use = "futures do nothing unless you `.await` or poll them"]

fn with_background<B>(self, background: B) -> ForegroundBackground<Self, B> where
    B: Future<Output = ()> + FusedFuture, 

Arrange for a future to run concurrently with a background future.

This method returns a new future that waits for self to complete while also concurrently running background. If background finishes before self, it will still wait for self to complete. If self finishes first, the future will resolve immediately and no longer poll background.

Example

use std::time::Duration;

use futures::future::FutureExt as _;
use futures::executor::block_on;
use async_channel::{bounded, Receiver, Sender};

use foreback::FutureExt as _;

/// Send pings forever to a channel
async fn ticker(sender: Sender<()>) {
    while let Ok(()) = sender.send(()).await {}
}

block_on(async {
    let (send, recv) = bounded(1);

    let result = async move {
        let mut counter = 0;

        for _ in 0..5 {
            let () = recv.recv().await.unwrap();
            counter += 1;
        }

        counter
    }
        .with_background(ticker(send).fuse())
        .await;

    assert_eq!(result, 5);
});

#[must_use = "futures do nothing unless you `.await` or poll them"]

fn with_try_background<B, E>(
    self,
    background: B
) -> TryForegroundBackground<Self, B> where
    B: Future<Output = Result<(), E>>, 

Arrange for a future to run concurrently with a fallible background future.

This method returns a new future that waits for self to complete while also concurrently running background. If background finishes before self, it will still wait for self to complete. If self finishes first, the future will resolve immediately and no longer poll background. If background finishes with an error, that error will be returned immediately, and self will no longer be polled.

Example

use std::time::Duration;

use futures::future::{FutureExt as _, pending};
use futures::executor::block_on;
use async_channel::{bounded, Receiver, Sender, SendError};

use foreback::FutureExt as _;

/// Send pings forever to a channel. Return an error if the channel closes.
async fn ticker(sender: Sender<()>) -> Result<(), SendError<()>> {
    loop {
        match sender.send(()).await {
            Ok(()) => {},
            Err(err) => return Err(err),
        }
    }
}

block_on(async {
    let (send, recv) = bounded(1);

    let result = async move {
        let mut counter = 0;

        for _ in 0..5 {
            let () = recv.recv().await.unwrap();
            counter += 1;
        }

        counter
    }
        .with_try_background(ticker(send).fuse())
        .await
        .unwrap();

    assert_eq!(result, 5);
});

block_on(async {
    let (send, recv) = bounded(1);

    let result = async move {
        let mut counter = 0;

        for _ in 0..5 {
            let () = recv.recv().await.unwrap();
            counter += 1;
        }

        drop(recv);
        let () = pending().await;
        counter
    }
        .with_try_background(ticker(send).fuse())
        .await
        .unwrap_err();
});

Loading content...

Implementors

impl<F: Future> FutureExt for F

Loading content...