Struct maitake::sync::wait_queue::WaitOwned

pub struct WaitOwned<Lock = DefaultMutex>
where
    Lock: ScopedRawMutex,
{ /* private fields */ }

Available on crate feature alloc only.

Future returned from WaitQueue::wait_owned().

This is identical to the Wait future, except that it takes an Arc reference to the WaitQueue, allowing the returned future to live for the 'static lifetime.

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 WaitOwned future once it has been polled. For instance, the following code must not compile:

 use maitake_sync::wait_queue::WaitOwned;

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

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

Implementations

impl<Lock> WaitOwned<Lock>

where Lock: ScopedRawMutex,

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

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

Examples

use maitake_sync::WaitQueue;
use std::sync::Arc;

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

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

pub fn same_queue(&self, other: &WaitOwned<Lock>) -> bool

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

Examples

Two WaitOwned futures waiting on the same WaitQueue return true:

use maitake_sync::WaitQueue;
use std::sync::Arc;

let queue = Arc::new(WaitQueue::new());

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

Two WaitOwned futures waiting on different WaitQueues return false:

use maitake_sync::WaitQueue;
use std::sync::Arc;

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

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

pub fn subscribe(self: Pin<&mut WaitOwned<Lock>>) -> Poll<Result<(), Closed>>

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

Polling a WaitOwned 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 WaitOwned future is in the list of waiters before the future is polled for the rst 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 WaitOwned future to wait on the queue. This method allows registering the WaitOwned future with the queue prior to checking the external state, without actually sleeping, so that when the task does wait for the WaitOwned future to complete, it will have received any wakeup that was sent between when the external state was checked and the WaitOwned 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 WaitOwned future 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 WaitOwned future subscribed to wakeups from the queue, and has not been woken, this method returns Poll::Pending.

Trait Implementations

impl<Lock> Debug for WaitOwned<Lock>

where Lock: Debug + ScopedRawMutex,

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

Formats the value using the given formatter.

impl<Lock> Drop for WaitOwned<Lock>

where Lock: ScopedRawMutex,

fn drop(&mut self)

Executes the destructor for this type.

impl<Lock> Future for WaitOwned<Lock>

where Lock: ScopedRawMutex,

type Output = Result<(), Closed>

The type of value produced on completion.

fn poll( self: Pin<&mut WaitOwned<Lock>>, cx: &mut Context<'_> ) -> Poll<<WaitOwned<Lock> 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, Lock> Unpin for WaitOwned<Lock>

where Lock: ScopedRawMutex, __WaitOwned<'pin, Lock>: Unpin,