Skip to main content

AdmittedRing

Struct AdmittedRing 

Source
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

Source

fn new(ring: SurbRingBuffer<HoprSurb>, epoch: u64) -> Self

Source

fn epoch(&self) -> u64

Source

fn stamp_epoch(&self, epoch: u64)

Methods from Deref<Target = SurbRingBuffer<HoprSurb>>§

Source

pub fn capacity(&self) -> usize

The ceiling on how many SURBs this buffer retains.

Source

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 (a Put of a fresh ring would trip the admitted cache’s Replaced listener 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.

Source

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.

Source

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.

Source

pub fn pop_next_valid<F>(&self, is_valid: F) -> Option<PoppedSurb<S>>
where F: Fn(&HoprSurbId, &S) -> bool,

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.

Source

fn len(&self) -> usize

Number of SURBs currently held, across both tiers.

Source

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.

Source

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

Source§

fn clone(&self) -> AdmittedRing

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for AdmittedRing

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Deref for AdmittedRing

Source§

type Target = SurbRingBuffer<SURB<Ed25519Suite, HoprSphinxHeaderSpec>>

The resulting type after dereferencing.
Source§

fn deref(&self) -> &Self::Target

Dereferences the value.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> DynClone for T
where T: Clone,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> FutureExt for T

§

fn with_context(self, otel_cx: Context) -> WithContext<Self>

Attaches the provided Context to this type, returning a WithContext wrapper. Read more
§

fn with_current_context(self) -> WithContext<Self>

Attaches the current Context to this type, returning a WithContext wrapper. Read more
§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts 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
§

impl<T> Pointable for T

§

const ALIGN: usize

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
§

impl<T> PolicyExt for T
where T: ?Sized,

§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] only if self and other return Action::Follow. Read more
§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] if either self or other returns Action::Follow. Read more
§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<P, T> Receiver for P
where P: Deref<Target = T> + ?Sized, T: ?Sized,

Source§

type Target = T

🔬This is a nightly-only experimental API. (arbitrary_self_types)
The target type on which the method may be called.
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more