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<List> Group<List>
impl<List> Group<List>
Sourcepub fn attach<F: Future + Unpin>(
self,
fut: F,
) -> (Handle<F>, Group<At<F, List>>)
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);
Sourcepub fn detach<I, F: Future>(
self,
handle: Handle<F>,
) -> (ReadyOrNot<F>, Group<List::Output>)where
List: Detach<F, I>,
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);
Sourcepub fn wait_for<F>(&mut self, fut: F) -> WaitFor<'_, F, List> ⓘ
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);
Sourcepub async fn detach_and_wait_for<I, F: Future>(
self,
handle: Handle<F>,
) -> (F::Output, Group<<List as Detach<F, I>>::Output>)
pub async fn detach_and_wait_for<I, F: Future>( self, handle: Handle<F>, ) -> (F::Output, Group<<List as Detach<F, I>>::Output>)
A convenience method for detach
ing 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);