Struct WorkerArrival 

pub struct WorkerArrival { /* private fields */ }

A live subscription to the next change in what dispatch selection can see, taken from ConnectedWorkerRegistry::worker_arrival and awaited as a future.

Why this is a value and not a bare wait method

The registry’s two wake sources — a registration (ConnectedWorkerRegistry::register and every sibling, through their shared tail) and a published reachability verdict (ConnectedWorkerRegistry::set_dispatch_ineligible) — are both Notify::notify_waiters, which stores no permit. A caller that reads the registry, misses, and only then constructs its wait has already lost any arrival that landed during the read: the broadcast fired into an empty waiter list. That caller then sleeps on a pool it holds positive evidence is served, until some unrelated later registration happens to wake it — and on the gRPC transport, where no liveness probe runs and no verdict is ever published, an unrelated registration is the ONLY thing that ever could.

So the subscription is a value the caller takes before it looks, and awaits after it has missed. Everything that fires in between is retained.

Why it is retained — tokio 1.52.3 at the bytes

Line numbers are in tokio-1.52.3/src/sync/notify.rs, the version Cargo.lock pins.

• Notify::notified_owned (:613) snapshots the process-wide notify_waiters call counter into the future at construction (:619, notify_waiters_calls: get_num_notify_waiters_calls(state)).
• notify_waiters (:743) increments that counter unconditionally — inner_notify_waiters bumps it at :755 when nobody is parked and at :761 when someone is. A broadcast into an empty list is therefore not lost; it moves a number.
• poll_notified’s State::Init arm compares the snapshot against the live counter at :1124, and again under the waiter lock at :1156; a difference sends the future straight to State::Done → Poll::Ready.

That comparison is the retention property, and it belongs to construction. OwnedNotified::enable (:1059) is called here too: it runs that same Init arm eagerly and, on the not-yet-notified path, pushes the waiter into the list at :1219 — so the waiter is registered at a defined point rather than at first poll, and a notify_one permit would be retained as well if one were ever added to this Notify. There is none today; this type must not rest its correctness on that staying true.

What it costs

OwnedNotified rather than the borrowed Notified<'_> because the value crosses a &mut dyn FnMut(..) boundary (the wait path’s park contract) and sits in a tokio::select! arm (the bridge’s park); the borrowed form forces a higher-ranked bound through the first and pinning ceremony at the second.

Pin<Box<_>> because enable needs Pin<&mut Self> at construction, and because it makes this type Unpin so no call site owes pinning ceremony. The price is one heap allocation per selection-loop iteration, on a path that is about to park. The alternative — hand back a bare OwnedNotified and ask every call site to remember pin! and enable() — puts the obligation back on the call sites, and a call site that forgot its obligation is precisely the defect this type exists to end.

Trait Implementations

impl Debug for WorkerArrival

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

Formats the value using the given formatter.

impl Future for WorkerArrival

type Output = ()

The type of value produced on completion.

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

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.