Struct Shared 

pub struct Shared<F: Future> { /* private fields */ }

A cloneable future that drives F through whichever clone is polled and resolves every clone to a clone of its output.

Several tasks can wait on one future without a task of its own, and each completes even if the clone that created the future is never polled again. Clones complete together, and a clone polled after completion resolves immediately. Dropping the last clone drops the inner future, or its output, after which no WeakShared handle can recover it.

Polling requires F to be Unpin (box it first otherwise) and its output to be Clone. The shared state is itself the inner future’s waker, and a waker must be 'static, Send, and Sync, so F must also be Send and 'static, and its output Send and Sync.

Liveness

Exactly one clone polls the inner future at a time. A clone polled meanwhile registers its waker and returns Poll::Pending without waiting for that poll. A clone’s waker stays registered until the clone completes or is dropped, and waking the inner future wakes every registered clone. If the inner future is woken while a clone polls it, or another clone finds it busy meanwhile, the polling clone wakes every other clone again once it stops polling, so a clone that went back to sleep after finding the inner future busy observes what that poll did and polls the inner future if it was woken. Progress therefore never depends on any particular clone being polled again. A clone may stop polling, because it is dropped or finished through another path, without stranding the others. A clone polled when the inner future was not woken since its last poll only registers, so the inner future is polled about once per wake however many clones are woken.

Panics

A panic while polling the inner future propagates to the polling clone and poisons the future. Every waiting clone is woken, and polling any clone afterwards panics.

Wakers

Registered wakers are cloned while the shared state is locked, and that lock is not reentrant, so cloning a registered waker must not wake this future’s inner future, or poll or drop one of its clones. Wakes, and drops of displaced wakers, happen after unlocking.

Implementations

impl<F: Future> Shared<F>

pub fn new(future: F) -> Self

Share future among the clones of the returned Shared.

pub fn downgrade(&self) -> WeakShared<F>

Create a WeakShared handle to this future.

pub fn ptr_eq(&self, other: &Self) -> bool

Whether self and other are clones of the same future, whether or not it completed.

Trait Implementations

impl<F: Future> Clone for Shared<F>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<F: Future> Drop for Shared<F>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<F> Future for Shared<F>

where F: Future + Send + Unpin + 'static, F::Output: Clone + Send + Sync,

type Output = <F as Future>::Output

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<F::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.