Struct Wait

Source

pub struct Wait<'a, Lock: ScopedRawMutex = DefaultMutex> { /* 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.

§Notes

This future is !Unpin, as it is unsafe to core::mem::forget a Wait future once it has been polled. For instance, the following code must not compile:

 use maitake_sync::wait_queue::Wait;

 // Calls to this function should only compile if `T` is `Unpin`.
 fn assert_unpin<T: Unpin>() {}

 assert_unpin::<Wait<'_>>();

Implementations§

Source §

impl<Lock: ScopedRawMutex> Wait<'_, Lock>

Source

pub fn waits_on(&self, queue: &WaitQueue<Lock>) -> 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<'_, Lock>) -> 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));

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:

The WaitQueue::wake() method was called between the creation of the Wait and the call to this method.
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.
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.
The WaitQueue has been closed, in which case this method returns Poll::Ready(Err(Closed)).