Struct ServiceGate 

pub struct ServiceGate {
    served: AtomicU64,
    served_predeposit: AtomicU64,
    predeposit_budget: u64,
    remaining: AtomicU64,
    funded: AtomicBool,
    mode_epoch: AtomicU64,
    poisoned: AtomicBool,
    notify: SlotNotify,
    ceiling: AtomicU64,
    served_at_last_progress: AtomicU64,
}

Bounded predeposit service gate for a single PIX session.

Parking

While the front is unfunded, exhausting its predeposit budget parks acquire. Once funded, exceeding the served-without-progress ceiling parks on the same mechanism. On release_service, withhold_service, notify_progress, or poison, all parked callers are woken.

Fields

served: AtomicU64

Monotonic number of packets served.

served_predeposit: AtomicU64

Of those, the ones taken from a predeposit allowance rather than from funded service.

Monotonic over the life of the gate and never reset by a rotation, so it is a share of served rather than a per-front figure — see served_split, which is the only reader.

predeposit_budget: u64

Predeposit budget restored after each paid front-cycle handoff.

remaining: AtomicU64

Remaining predeposit budget (tracked separately so we can park on 0).

funded: AtomicBool

Whether the current front cycle is funded.

mode_epoch: AtomicU64

Incremented after every mode publication.

Permit acquisition performs an RMW on this epoch before committing its counter update. That gives mode transitions and permits one atomic ordering point: a permit either belongs to the old front or observes the new mode, rather than loading funded before a transition and committing after it.

poisoned: AtomicBool

Whether the gate is poisoned.

notify: SlotNotify

Waker for parked writers.

ceiling: AtomicU64

Ceiling on packets served since last progress notification.

served_at_last_progress: AtomicU64

Snapshot of served at last progress notification.

Implementations

impl ServiceGate

pub fn new( predeposit_budget: u64, max_served_without_progress: u64, ) -> Arc<Self>

Create a new gate with the given predeposit budget and progress ceiling.

pub async fn acquire(self: &Arc<Self>) -> Result<(), GateClosed>

Acquire a service permit.

After funding, enforces a ceiling on packets served without SSA recovery progress (see the ceiling field). Parks on SlotNotify when the ceiling or predeposit budget is exceeded.

pub fn served_total(&self) -> u64

Current value of the served counter.

pub fn predeposit_exposure(&self) -> u64

Packets served against the current front’s predeposit allowance and not yet paid for.

Zero while funded, and that is the definition rather than an approximation: funding is exactly the event that converts the allowance the current front spent into service the Entry has paid for, so there is nothing outstanding to report. A later withhold_service restores the whole allowance for an unfunded successor, and the figure starts climbing again from zero for that cycle.

Read once per supervisor turn rather than per packet, so the two relaxed loads are not on any hot path.

fn mode_is_current(&self, epoch: u64) -> bool

Linearization point shared by a permit and mode publication.

pub fn release_service(self: &Arc<Self>)

Publish funded mode for the current front and wake all parked writers.

acquire then enforces the served-without-progress ceiling instead of the predeposit budget. Calling this while already funded represents a funded-to-funded front handoff and starts the new front with a fresh ceiling window.

Snapshots served_total into served_at_last_progress so the ceiling check starts from the moment of funding and does not count predeposit packets against the post-funding budget.

pub fn withhold_service(self: &Arc<Self>)

Return to predeposit mode for the next unfunded front cycle.

The allowance is restored before the mode is published, so a permit that observes the new epoch also observes the complete budget. Parked ceiling waiters are woken to re-evaluate the predeposit branch; with a zero allowance they correctly park again.

pub fn notify_progress(self: &Arc<Self>)

Record SSA recovery progress: snapshots the served counter so the ceiling reopens, and wakes any writers parked on the ceiling.

pub fn poison(&self)

Poison the gate: prevent all further acquires.

Parked and future callers receive GateClosed.

Semantics

After poison() returns, at most one in-flight acquire() per concurrent caller may still observe the gate as not poisoned (a parked awaiter that wakes before the poison store is visible).

pub fn try_acquire_sync(&self) -> Result<GateVerdict, GateClosed>

Non-blocking try-acquire — the egress fast path.

Returns GateVerdict::Admitted on success, GateVerdict::Blocked with the reason if the predeposit budget is exhausted (and the gate not yet funded) or the ceiling is exceeded (gate funded), or GateClosed if poisoned.

Blocked means the gate refused, and only ever that: both branches retry a lost compare-exchange rather than reporting it. Contention on served is not a refusal — service was available and the caller would be turned away anyway — and with several concurrent egress writers, reporting it as one converts contention into spurious refusals on the documented fast path.

Every outgoing data packet of a supervised Session comes through here, and service is available for all but a vanishing fraction of them, so this answering synchronously is what keeps gating off the allocator: only acquire’s parking path needs a future large enough to box, and that path is about to block anyway. The same argument is why the funded branch below does not count anything of its own: it is the steady state, at the Session’s full packet rate, and the split it would produce is available by subtraction.

pub fn served_split(&self) -> (u64, u64)

Packets this gate has admitted, split into (predeposit, funded).

Counted on the predeposit branch only, and derived for the funded one. That asymmetry is the whole point: at deployed dimensions the funded branch carries essentially all of a Session’s egress — tens of thousands of packets a second across a node — while the predeposit branch carries at most max_predeposit_packets per front rotation. A second fetch_add on the steady-state path would be paid on every packet to produce a number that subtraction already gives exactly.

The publication order, and why it is that way round

The two loads are not atomic with respect to each other, so a concurrent predeposit permit can land between them and be seen by one load but not the other. Which of the two tears is possible decides whether that permit is merely late or is actually miscounted, and the writers pick which by the order they publish in.

A predeposit permit therefore increments served_predeposit first and publishes served with Release. The acquire load of served below synchronizes with that store, so seeing the permit in the total guarantees seeing it in the predeposit count too: the derived funded figure can never come out one high, which would report a predeposit packet as funded and then report it again as predeposit on the next read.

The surviving tear is the harmless one — served_predeposit new against served old, which makes the derived funded figure one low. Nothing is lost and the next read is consistent again, but a consumer keeping a watermark must not store the regressed value or it will re-cross that ground: see PixSessionTelemetry::flush_egress, which clamps.