struct AdmittedRing {
ring: SurbRingBuffer<HoprSurb>,
epoch: Arc<AtomicU64>,
}Expand description
An admitted ring together with the number naming the admission that installed it.
The pairing is what a deferred SurbStore::retire checks: it removes the entry only when its
token still equals the number stored here, so a retire that arrives after a successor Session was
admitted on the same pseudonym is a no-op rather than a destruction of the successor’s ring. The
two live in one cache entry so the compare in retire and the removal are a single atomic
operation over the key — split across two caches, an admit could land between the compare and
the removal and the retire would destroy the successor’s ring.
epoch is behind an Arc so it can be re-stamped in place: admit of a re-admitted pseudonym
must keep the resident ring (it must not discard what it already holds), and replacing the entry
wholesale to carry a new number would trip moka’s Replaced path — which the admitted cache’s
listener books as an eviction the ring never actually suffered. Storing through the Arc changes
only the number, and it happens inside SurbStore::admit’s and_compute_with, under the same
key-level lock retire compares under — so an entry is never observable with one admission’s
ring and a later admission’s number, nor with no number at all.
Fields§
§ring: SurbRingBuffer<HoprSurb>§epoch: Arc<AtomicU64>The number next_admission_epoch minted for the admission that installed ring, or
re-stamped it on a re-admission. Never zero: zero is the token a teardown of a never-admitted
Session presents, and it must match no entry.
Implementations§
Source§impl AdmittedRing
impl AdmittedRing
Methods from Deref<Target = SurbRingBuffer<HoprSurb>>§
Sourcefn raise_capacity(&self, to: usize)
fn raise_capacity(&self, to: usize)
Raises this buffer’s ceiling to at least to retained SURBs, never lowering it.
Two callers raise a ceiling, and both are about a target the ring was not sized for:
SurbStore::admit, when a pseudonym is re-admitted. It keeps the resident ring rather than replacing it (aPutof a fresh ring would trip the admitted cache’sReplacedlistener and be booked as an eviction the ring never suffered), but the successor Session may have announced a larger SURB target than its predecessor.MemorySurbStore::raise_admitted_capacity, when a live peer raises its announced target mid-Session and says so in a keep-alive.
Without this the resident ring would keep the smaller ceiling for the Session’s whole
lifetime, and once its balancer filled past it, push would evict — losing PIX shares
permanently, with nothing but an evicted count to show for it.
The raise is monotone on purpose. Narrowing on a re-admission would strand SURBs a live Session
may already have inserted and would make the ceiling depend on admission order; fetch_max
makes the effective ceiling the largest target any admission of the pseudonym has requested.
A concurrent push racing the raise simply reads whichever ceiling it sees: growing it can only
turn a would-be eviction into a clean insert.
Sourcefn take_all(&self) -> (Option<u8>, Vec<(HoprSurbId, S)>)
fn take_all(&self) -> (Option<u8>, Vec<(HoprSurbId, S)>)
Removes every SURB held and returns them with the generation they were pushed at.
Used to move a ring between the store’s two classes: the caller pushes the returned batch into the destination ring, whose own generation logic then decides how the two merge (append, supersede or discard). The returned order is pop order — share-bearing SURBs first, each tier oldest first — not the arrival order, which is the order that matters to a consumer.
Sourcefn push_counting<I: IntoIterator<Item = (HoprSurbId, S)>>(
&self,
surbs: I,
generation: u8,
) -> (SurbInsertOutcome, usize)where
S: SurbShareInfo,
fn push_counting<I: IntoIterator<Item = (HoprSurbId, S)>>(
&self,
surbs: I,
generation: u8,
) -> (SurbInsertOutcome, usize)where
S: SurbShareInfo,
Pushes all SURBs of one batch, stamped with generation, evicting past capacity.
A batch is minted at a single generation by the creator (one packet’s worth of SURBs), so a
single generation covers the whole surbs iterator. Relative to the highest generation
seen so far:
- newer → both tiers are cleared before inserting, so SURBs for the superseded return path are dropped at once rather than lingering until they drain;
- equal → the batch is appended (an ordinary refill);
- older → the batch is discarded as a late/reordered leftover.
Each SURB is sorted into the share-bearing or the share-less tier by SurbShareInfo. Once at
capacity, every one that arrives costs the buffer one SURB, share-less before share-bearing:
- if a share-less SURB is held, the oldest of them is evicted;
- else, a share-less newcomer is refused: it is only a return path, and a share-bearing SURB is that plus a share nothing can replace;
- else, only shares are held and the newcomer carries one too, so the oldest share-bearing SURB is evicted.
A refused newcomer counts as evicted all the same: it is a SURB the buffer had no room for. Under
PIX an evicted share-bearing SURB is a lost SSA share, not merely a lost SURB — see
SurbStoreConfig::rb_capacity — so those are counted on their own, as evicted_shares: the
exact number of shares the push lost to overflow, a subset of evicted.
Returns what the push did; the eviction count is what lets a caller notice the overflow at
all, since dropping a SURB is otherwise indistinguishable from a clean insert.
It counts capacity overflow only: SURBs dropped because a newer generation superseded them
were already unusable, and reporting them as pressure would ask the creator to slow down
because it re-planned its own return path. They are reported separately, as
superseded: the whole of what a newer generation cleared, or
the whole of an older-generation batch that was refused. The caller that tracks what the buffer
holds adds the two, so that retained and its own count of what was received agree.
Also returns how many share-carrying SURBs the generation rule took out of play: the shares a newer generation cleared, or those of an older-generation batch it refused.
Sourcepub fn pop_next_valid<F>(&self, is_valid: F) -> Option<PoppedSurb<S>>
pub fn pop_next_valid<F>(&self, is_valid: F) -> Option<PoppedSurb<S>>
Pops the next SURB that is_valid accepts: a share-bearing one while any is held, the oldest of
each tier first.
Destructive: rejected entries are discarded, not skipped, so an unusable SURB neither is
handed out nor blocks those behind it. Pass only a validity test — a selective predicate
(say, a routing preference) would drain the buffer. None once it is exhausted without a
match.
is_valid runs outside the lock: it is caller-supplied and may take locks of its own, so
calling it inside the critical section would invite lock-order inversion.
Sourcefn tier_lens(&self) -> (usize, usize)
fn tier_lens(&self) -> (usize, usize)
Number of SURBs currently held in each tier, as (share-bearing, share-less): len
split the way a pop sees it, share-bearing first. Both are read under one lock, so they are a
consistent pair.
Sourcepub fn pop_one_if_has_id(&self, id: &HoprSurbId) -> Option<PoppedSurb<S>>
pub fn pop_one_if_has_id(&self, id: &HoprSurbId) -> Option<PoppedSurb<S>>
Pops the next SURB (the one pop_next_valid would take first) only if it has
the given ID.
Trait Implementations§
Source§impl Clone for AdmittedRing
impl Clone for AdmittedRing
Source§fn clone(&self) -> AdmittedRing
fn clone(&self) -> AdmittedRing
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read moreSource§impl Debug for AdmittedRing
impl Debug for AdmittedRing
Source§impl Deref for AdmittedRing
impl Deref for AdmittedRing
Source§type Target = SurbRingBuffer<SURB<Ed25519Suite, HoprSphinxHeaderSpec>>
type Target = SurbRingBuffer<SURB<Ed25519Suite, HoprSphinxHeaderSpec>>
Auto Trait Implementations§
impl !RefUnwindSafe for AdmittedRing
impl !UnwindSafe for AdmittedRing
impl Freeze for AdmittedRing
impl Send for AdmittedRing
impl Sync for AdmittedRing
impl Unpin for AdmittedRing
impl UnsafeUnpin for AdmittedRing
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
§impl<T> FutureExt for T
impl<T> FutureExt for T
§fn with_context(self, otel_cx: Context) -> WithContext<Self>
fn with_context(self, otel_cx: Context) -> WithContext<Self>
§fn with_current_context(self) -> WithContext<Self>
fn with_current_context(self) -> WithContext<Self>
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more