Struct ObjectWaiter 

pub struct ObjectWaiter { /* private fields */ }

A blocking object that waits for signals on Zircon objects, and that can be interrupted.

InterruptibleEvent and PortEvent wake up a thread when another thread notifies or interrupts it. A thread that must also wake up when a Zircon object is signaled, such as a channel it reads requests from, would have to observe the object through a port, or an async executor. Instead, ObjectWaiter lets the thread wait for the objects directly with zx_object_wait_many: the waiter adds an event of its own to the objects the thread waits for, and interrupt signals that event.

To block using an ObjectWaiter, first call begin_wait. At this point, the waiter is in the “waiting” state, and future calls to interrupt will terminate the wait.

After begin_wait returns, call wait_many on the returned guard to block the current thread until one of the following conditions occur:

1. One of the given objects asserts one of the signals that it is waited for.
2. The given deadline expires.
3. interrupt was called after begin_wait.

It’s safe to call interrupt at any time. However, only one thread can wait on an ObjectWaiter at a time: begin_wait cannot be called again until the guard it returns is consumed by wait_many, or dropped.

ObjectWaiter uses two-phase waiting so that clients can register the waiter with the code that interrupts them, for example in the RunState of a task, and then start blocking. This approach ensures that clients do not miss interruptions that arrive after they register the waiter but before they actually start blocking, while the interruptions of previous waits, which arrive before begin_wait, are ignored.

The event of the waiter is only signaled when a wait is actually interrupted, and only cleared after such a wait, so that a wait that is not interrupted costs no more syscall than zx_object_wait_many itself.

As with InterruptibleEvent and PortEvent, a wait that remains blocked for STACK_CLEAN_DELAY wakes up once to decommit the unused pages of the stack of the thread with starnix_stack::clean_stack, and then blocks again until the deadline.

Implementations

impl ObjectWaiter

pub fn new() -> Arc<Self>

pub fn begin_wait<'a>(self: &'a Arc<Self>) -> ObjectWaitGuard<'a>

Called to initiate a wait.

Calls to interrupt after this function returns, and before the wait ends, will cause wait_many to return ObjectWaitError::Interrupted. Calls to interrupt prior to calling begin_wait, or after the wait ended, are ignored.

Once called, this function cannot be called again until the returned guard is consumed by wait_many, or dropped. Otherwise, this function will panic.

pub fn interrupt(&self)

Interrupts the wait in progress.

If no wait is in progress, that is, before begin_wait or after the wait ended, the interruption is ignored. Otherwise, wait_many returns ObjectWaitError::Interrupted, whether it is already blocked or not. Calling this function repeatedly has no effect.

Trait Implementations

impl Debug for ObjectWaiter

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

Formats the value using the given formatter.