pub struct WaitOwned<Lock: ScopedRawMutex = DefaultMutex> { /* private fields */ }
Available on crate feature alloc only.
Expand description

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§

source§

impl<Lock: ScopedRawMutex> WaitOwned<Lock>

source

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

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

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

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§

source§

impl<Lock: Debug + ScopedRawMutex> Debug for WaitOwned<Lock>

source§

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

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

impl<Lock: ScopedRawMutex> Drop for WaitOwned<Lock>

source§

fn drop(&mut self)

Executes the destructor for this type. Read more
source§

impl<Lock: ScopedRawMutex> Future for WaitOwned<Lock>

§

type Output = Result<(), Closed>

The type of value produced on completion.
source§

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

Attempt 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, Lock: ScopedRawMutex> Unpin for WaitOwned<Lock>
where __WaitOwned<'pin, Lock>: Unpin,

Auto Trait Implementations§

§

impl<Lock = DefaultMutex> !RefUnwindSafe for WaitOwned<Lock>

§

impl<Lock> Send for WaitOwned<Lock>
where Lock: Sync + Send,

§

impl<Lock = DefaultMutex> !Sync for WaitOwned<Lock>

§

impl<Lock = DefaultMutex> !UnwindSafe for WaitOwned<Lock>

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.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
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.
§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more