Struct maitake::sync::wait_queue::Wait

pub struct Wait<'a> { /* private fields */ }

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

impl Wait<'_>

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

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

pub fn subscribe(self: Pin<&mut Wait<'_>>) -> Poll<Result<(), Closed>>

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

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

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

Formats the value using the given formatter.

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

fn drop(&mut self)

Executes the destructor for this type.

impl Future for Wait<'_>

type Output = Result<(), Closed>

The type of value produced on completion.

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

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

impl<'pin, 'a> Unpin for Wait<'a>

where __Wait<'pin, 'a>: Unpin,