Struct maitake_sync::wait_queue::Wait

source ·
pub struct Wait<'a> { /* private fields */ }
Expand description

Future returned from WaitQueue::wait().

This future is fused, so once it has completed, any future calls to poll will immediately return Poll::Ready.

Implementations§

source§

impl Wait<'_>

source

pub fn waits_on(&self, queue: &WaitQueue) -> bool

Returns true if this Wait future is waiting for a notification from the provided WaitQueue.

§Examples
use maitake_sync::WaitQueue;

let queue1 = WaitQueue::new();
let queue2 = WaitQueue::new();

let wait = queue1.wait();
assert!(wait.waits_on(&queue1));
assert!(!wait.waits_on(&queue2));
source

pub fn same_queue(&self, other: &Wait<'_>) -> bool

Returns true if self and other are waiting on a notification from the same WaitQueue.

§Examples

Two Wait futures waiting on the same WaitQueue return true:

use maitake_sync::WaitQueue;

let queue = WaitQueue::new();

let wait1 = queue.wait();
let wait2 = queue.wait();
assert!(wait1.same_queue(&wait2));
assert!(wait2.same_queue(&wait1));

Two Wait futures waiting on different WaitQueues return false:

use maitake_sync::WaitQueue;

let queue1 = WaitQueue::new();
let queue2 = WaitQueue::new();

let wait1 = queue1.wait();
let wait2 = queue2.wait();
assert!(!wait1.same_queue(&wait2));
assert!(!wait2.same_queue(&wait1));
source

pub fn subscribe(self: Pin<&mut Self>) -> Poll<WaitResult<()>>

Eagerly subscribe this future to wakeups from WaitQueue::wake().

Polling a Wait future adds that future to the list of waiters that may receive a wakeup from a WaitQueue. However, in some cases, it is desirable to subscribe to wakeups prior to actually waiting for one. This method should be used when it is necessary to ensure a Wait future is in the list of waiters before the future is polled for the first time.

In general, this method is used in cases where a WaitQueue must synchronize with some additional state, such as an AtomicBool or counter. If a task first checks that state, and then chooses whether or not to wait on the WaitQueue based on that state, then a race condition may occur where the WaitQueue wakes waiters between when the task checked the external state and when it first polled its Wait future to wait on the queue. This method allows registering the Wait future with the queue prior to checking the external state, without actually sleeping, so that when the task does wait for the Wait future to complete, it will have received any wakeup that was sent between when the external state was checked and the Wait future was first polled.

§Returns

This method returns a Poll<WaitResult> which is Ready a wakeup was already received. This method returns Poll::Ready in the following cases:

  1. The WaitQueue::wake() method was called between the creation of the Wait and the call to this method.
  2. This is the first call to subscribe or poll on this future, and the WaitQueue was holding a stored wakeup from a previous call to wake(). This method consumes the wakeup in that case.
  3. The future has previously been subscribed or polled, and it has since then been marked ready by either consuming a wakeup from the WaitQueue, or by a call to wake() or wake_all() that removed it from the list of futures ready to receive wakeups.
  4. The WaitQueue has been closed, in which case this method returns Poll::Ready(Err(Closed)).

If this method returns Poll::Ready, any subsequent polls of this Wait future will also immediately return Poll::Ready.

If the Wait future subscribed to wakeups from the queue, and has not been woken, this method returns Poll::Pending.

Trait Implementations§

source§

impl<'a> Debug for Wait<'a>

source§

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

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

impl<'a> Drop for Wait<'a>

source§

fn drop(&mut self)

Executes the destructor for this type. Read more
source§

impl Future for Wait<'_>

§

type Output = Result<(), Closed>

The type of value produced on completion.
source§

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

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

impl<'pin, 'a> Unpin for Wait<'a>
where __Wait<'pin, 'a>: Unpin,

Auto Trait Implementations§

§

impl<'a> !Freeze for Wait<'a>

§

impl<'a> !RefUnwindSafe for Wait<'a>

§

impl<'a> Send for Wait<'a>

§

impl<'a> !Sync for Wait<'a>

§

impl<'a> !UnwindSafe for Wait<'a>

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> 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<F> IntoFuture for F
where F: Future,

§

type Output = <F as Future>::Output

The output that the future will produce on completion.
§

type IntoFuture = F

Which kind of future are we turning this into?
source§

fn into_future(self) -> <F as IntoFuture>::IntoFuture

Creates a future from a value. Read more
source§

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

§

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>,

§

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.