Struct DrainTrigger 

pub struct DrainTrigger { /* private fields */ }

One-shot trigger that lets admin_v1_drain wake the runtime’s main select loop and request graceful shutdown (issue #244). Modelled on tokio::sync::Notify so the RPC handler can fire-and-return without blocking on the runtime’s shutdown latency. The runtime awaits wait in its select loop; firing twice is a no-op (the second notify_one coalesces, same as Notify).

wait_admin (issue #604) is a per-drain configuration bit: fire takes it as a parameter. First writer wins — once a fire has established the value, subsequent fires return that same value rather than overwriting. This gives two concurrent drain RPCs one well-defined outcome: the effective wait_admin value the runtime will see is the first one written, and every response reports that same value.

Cross-thread visibility comes from the Notify::notify_one → Notify::notified() happens-before edge: the runtime’s wait_admin load is sequenced after notified() resolves, and tokio’s Notify publishes prior writes (including the OnceLock store) on that edge. The OnceLock’s own synchronization is belt-and-braces — important only for readers that don’t go through wait().

Implementations

impl DrainTrigger

pub fn new() -> Self

Create a new DrainTrigger.

pub fn fire(&self, wait_admin: bool) -> bool

Signal the runtime to begin graceful shutdown with the requested wait_admin ordering. Returns the effective value the runtime will see — equal to wait_admin if this is the first fire, or the prior writer’s value if a fire already happened. The drain RPC uses the return as the wait_admin_honored ack so callers see the truth about what the runtime will actually do, even under a concurrent-drain race (issue #604 review).

Fire-and-forget: calling this more than once is a no-op as far as wake-up goes (the second notify_one coalesces into the pending permit the first call stored).

pub fn wait_admin(&self) -> bool

Read the current wait_admin value. false when no fire has happened yet (runtime should pick the SIGTERM-equivalent ordering). The runtime calls this only after wait() has resolved, at which point OnceLock::get() returns Some.

pub async fn wait(&self)

Wait until fire is called. Returns immediately if fire was already called before wait was polled.

Trait Implementations

impl Debug for DrainTrigger

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

Formats the value using the given formatter.

impl Default for DrainTrigger

fn default() -> Self

Returns the “default value” for a type.