Struct Group

Source

pub struct Group<List> { /* private fields */ }

Expand description

This type defines a specific set of futures that are driven whenever a future is awaited through a group’s cooperation.

Implementations§

Source §

impl Group<Empty>

Source

pub const fn new() -> Self

Constructs a new group with no attached futures.

Source §

impl<List> Group<List>

Source

pub fn attach<F: Future + Unpin>( self, fut: F, ) -> (Handle<F>, Group<At<F, List>>)

Adds a future to this group’s set of background futures. The future must be Unpin, or be pinned in external storage before being attached.

This method consumes self and returns a new group with the future attached, as well as a handle that can be used to later detach the future.

§Example

The most common way to use this method is to locally pin a future before attaching it.

let group = async_let::Group::new();

let fut = pin!(some_future()); // locally pin before attaching
let (handle, group) = group.attach(fut);

However, any pinning pointer to a future can be used.

let group = async_let::Group::new();

let mut fut = Box::pin(some_future()); // pin to the heap
let (handle, group) = group.attach(fut);

Source

pub fn detach<I, F: Future>( self, handle: Handle<F>, ) -> (ReadyOrNot<F>, Group<List::Output>)
where List: Detach<F, I>,

Removes a future from this group’s set of background futures. The future held by this group is relinquished and returned to the caller. The detached future may have been partially driven or even completed. If the future is already completed, then its output is saved and returned to the caller instead of the future.

This method consumes self and returns a new group with the future detached. If you want to additionally await the detached future, you can use Self::detach_and_wait_for as a convenience.

§Example

The primary reason for detaching a future without awaiting it is when its lifetime will end prior to it being driven to completion.

let group = async_let::Group::new();
let mut group = {
    // attach a short-lived future
    let fut = pin!(some_future());
    let (handle, group) = group.attach(fut);
     
    // ... do work with `fut` in the background ...

    // "error: temporary value dropped while borrowed" if commented
    let (fut, group) = group.detach(handle);
    group
};
// continue to use the group
let val = group.wait_for(some_other_future()).await;

§Type Inference

Usually, the future being detached is inferred from the provided handle. However, if multiple futures of the same type are attached to the group, then type inference will not be able to determine which future should be detached. In these cases, explicit disambiguation must be provided.

let group = async_let::Group::new();

let fut1 = pin!(some_future());
let (handle1, group) = group.attach(fut1);

let fut2 = pin!(some_future());
let (handle2, group) = group.attach(fut2);

// error: type annotations needed
// let (fut1, group) = group.detach(handle1);
use async_let::list::{S, Z};
let (fut1, group) = group.detach::<S<Z>, _>(handle1);

// type inference *can* infer the index now that the other future is detached
let (fut2, group) = group.detach(handle2);

Source

pub fn wait_for<F>(&mut self, fut: F) -> WaitFor<'_, F, List> ⓘ

Await a future while concurrently driving this group’s background futures. The background futures are not polled if the future being awaited does not suspend. The background futures share a context with the future being awaited, so the enclosing task will be awoken if any one of the background futures makes progress.

This method is used to await a future that is not in the set of background futures attached to this group. To await a future that is attached to this group, use Self::detach_and_wait_for.

§Example

let group = async_let::Group::new();

// ... attach futures to `group` ...

let output = group.wait_for(async { 3 + 7 }).await;
assert_eq!(output, 10);

Source

pub async fn detach_and_wait_for<I, F: Future>( self, handle: Handle<F>, ) -> (F::Output, Group<<List as Detach<F, I>>::Output>)
where List: Detach<F, I>, List::Output: FutList,

A convenience method for detaching a future followed by wait_for to get its output. If you do not wish to drive the background futures while awaiting the output, use Group::detach followed by ReadyOrNot::output.

§Example

let future = pin!(async { 3 + 7 });
let (handle, group) = group.attach(future);

// ... do other work with `future` in the background ...

let (output, group) = group.detach_and_wait_for(handle).await;
assert_eq!(output, 10);