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);

Trait Implementations§

Source§

impl<List: Clone> Clone for Group<List>

Source§

fn clone(&self) -> Group<List>

Returns a copy of the value. Read more
1.0.0 · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl<List: Debug> Debug for Group<List>

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl<List: Ord> Ord for Group<List>

Source§

fn cmp(&self, other: &Group<List>) -> Ordering

This method returns an Ordering between self and other. Read more
1.21.0 · Source§

fn max(self, other: Self) -> Self
where Self: Sized,

Compares and returns the maximum of two values. Read more
1.21.0 · Source§

fn min(self, other: Self) -> Self
where Self: Sized,

Compares and returns the minimum of two values. Read more
1.50.0 · Source§

fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized,

Restrict a value to a certain interval. Read more
Source§

impl<List: PartialEq> PartialEq for Group<List>

Source§

fn eq(&self, other: &Group<List>) -> bool

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
Source§

impl<List: PartialOrd> PartialOrd for Group<List>

Source§

fn partial_cmp(&self, other: &Group<List>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · Source§

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · Source§

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · Source§

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · Source§

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator. Read more
Source§

impl<List: Copy> Copy for Group<List>

Source§

impl<List: Eq> Eq for Group<List>

Source§

impl<List> StructuralPartialEq for Group<List>

Auto Trait Implementations§

§

impl<List> Freeze for Group<List>
where List: Freeze,

§

impl<List> RefUnwindSafe for Group<List>
where List: RefUnwindSafe,

§

impl<List> Send for Group<List>
where List: Send,

§

impl<List> Sync for Group<List>
where List: Sync,

§

impl<List> Unpin for Group<List>
where List: Unpin,

§

impl<List> UnwindSafe for Group<List>
where List: UnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.