Struct CompletionWake 

pub struct CompletionWake { /* private fields */ }

Tells the owner of an IoRing to drain it, on a thread-pool thread, whenever the ring’s completion queue may have gone from empty to non-empty (Model A, D-3; D-84).

The counterpart to EventDelivery for a caller that keeps its ring – behind its own lock, beside its own state – and wants the thread pool only to say when to drain. EventDelivery is this, with a drain that hands each completion to a callback, over a ring it owns.

What the owner owes

• Drain to empty on every call. The ring’s event is an edge, raised when the completion queue goes from empty to non-empty (D-19), so a call that leaves a completion queued may never be followed by another.
• Treat a call with nothing to pop as normal. There is one at setup, and each activation calls twice.
• One waiter per ring (D-21): no second wake over the same ring, and no other wait on its event. Stated, not enforced, because the wake does not hold the ring.
• Never drop the wake from inside its own call. Dropping it waits for a running call, which would be waiting for itself.

What the owner may rely on

Both are contract, as they are for EventDelivery (D-83):

• No lock and no ring is held while it calls. The wake holds no reference to the ring, so the owner may take its own lock in the call, pop, and push and submit more work.
• Calls may overlap. Two may run at once on different pool threads; the owner’s own lock is what serializes its ring.

Implementations

impl CompletionWake

pub fn new<T, X, K, F>( ring: &mut IoRing<T, X, K>, on_wake: F, env: Option<&mut CallbackEnviron<'_>>, ) -> Result<Self>

where F: Fn() + Send + Sync + 'static,

Wire ring’s completion event to a thread-pool wait that calls on_wake on a pool thread whenever the ring’s completion queue may have gone from empty to non-empty, and once at setup, so a backlog already queued is reached.

The protocol is EventDelivery’s: the event is attached unsignalled, the wait armed, and only then the setup signal raised – the order SetThreadpoolWait documents (“you must re-register the event with the wait object before signaling it each time to trigger the wait callback”); and each activation calls on_wake, re-arms, and calls on_wake again, the second call closing the gap a completion arriving before the re-arm would leave (M4.2, M26.9, M26.12).

env binds the wait’s pool – to a NUMA node’s, for instance; None is the process’s default pool.

Errors

io::ErrorKind::Unsupported if the running system does not report IORING_FEATURE_SET_COMPLETION_EVENT; this crate does not substitute a polling thread. Also any error from attaching the ring’s completion event, from ThreadpoolWait::new, or from raising the setup signal.

Trait Implementations

impl Drop for CompletionWake

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.