Struct ReplicationQueues 

pub struct ReplicationQueues { /* private fields */ }

Central queue manager for the replication pipeline.

Maintains three stages of the pipeline with global dedup:

1. PendingVerify – keys awaiting quorum verification.
2. FetchQueue – quorum-passed keys waiting for a fetch slot.
3. InFlightFetch – keys actively being downloaded.

Implementations

impl ReplicationQueues

pub fn new() -> Self

Create new empty queues.

pub fn add_pending_verify( &mut self, key: XorName, entry: VerificationEntry, ) -> AdmissionResult

Add a key to pending verification if not already present in any queue.

Returns an AdmissionResult distinguishing the three outcomes:

• Admitted — newly inserted.
• AlreadyPresent — Rule 8 cross-queue dedup (the key is already in pending_verify, fetch_queue, or in_flight_fetch); the existing entry remains and there is no work to retry.
• CapacityRejected — global or per-source bound hit; the work is genuinely lost and the caller (e.g. bootstrap drain accounting, source-side retry) MUST treat this as still-outstanding work, not as “done”. Without this distinction a bootstrap snapshot whose hints are capacity-rejected would silently mark itself drained.

pub fn get_pending(&self, key: &XorName) -> Option<&VerificationEntry>

Get a reference to a pending verification entry.

pub fn set_pending_state( &mut self, key: &XorName, state: VerificationState, ) -> Option<HintPipeline>

Advance a pending entry’s verification state, returning the entry’s pipeline (so the caller can branch on it) when the key was found.

Replaces a prior get_pending_mut which handed out &mut VerificationEntry and relied on a doc-comment to keep callers from re-assigning hint_sender. The per-source quota counter (pending_per_sender) is keyed by hint_sender recorded at admission; re-attributing a live entry to a different peer would orphan a count and silently desync the quota — exactly the silent-starvation class this fix prevents. Narrowing the mutation API to a single setter makes that mistake impossible to commit by accident.

pub fn remove_pending(&mut self, key: &XorName) -> Option<VerificationEntry>

Remove a key from pending verification.

pub fn pending_keys(&self) -> Vec<XorName>

Collect all pending verification keys (for batch processing).

pub fn pending_count(&self) -> usize

Number of keys in pending verification.

pub fn enqueue_fetch( &mut self, key: XorName, distance: XorName, sources: Vec<PeerId>, ) -> bool

Enqueue a key for fetch with its distance and verified sources.

Returns true if the candidate was enqueued, false if it was already present in any pipeline stage (Rule 8: cross-queue dedup) or the fetch_queue is at MAX_FETCH_QUEUE.

Callers that have removed the key from pending_verify immediately before this call should prefer promote_pending_to_fetch, which performs the move atomically and leaves the pending entry in place when the fetch queue is full (so verified work is retried on the next cycle instead of being silently lost).

pub fn promote_pending_to_fetch( &mut self, key: XorName, distance: XorName, sources: Vec<PeerId>, ) -> bool

Atomically promote a key from pending_verify to fetch_queue.

Checks fetch_queue capacity FIRST, then removes the pending entry and enqueues the fetch candidate. If fetch_queue is full, the pending entry is left in place so the next verification cycle can retry — preventing the silent-drop regression where a verified key removed from pending_verify could be dropped by a full fetch queue and lost from every stage.

Returns true on successful promotion, false when the fetch queue is at capacity (pending entry preserved).

pub fn dequeue_fetch(&mut self) -> Option<FetchCandidate>

Dequeue the nearest fetch candidate.

Returns None when the queue is empty. Silently skips candidates that are somehow already in-flight. Concurrency is enforced by the fetch worker, not by this method.

pub fn fetch_queue_count(&self) -> usize

Number of keys waiting in the fetch queue.

pub fn start_fetch( &mut self, key: XorName, source: PeerId, all_sources: Vec<PeerId>, )

Mark a key as in-flight (actively being fetched from source).

pub fn complete_fetch(&mut self, key: &XorName) -> Option<InFlightEntry>

Mark a fetch as completed (success or permanent failure).

pub fn retry_fetch(&mut self, key: &XorName) -> Option<PeerId>

Mark the current fetch attempt as failed and try the next untried source.

Returns the next source peer if one is available, or None if all sources have been exhausted.

pub fn in_flight_count(&self) -> usize

Number of in-flight fetches.

pub fn contains_key(&self, key: &XorName) -> bool

Check if a key is present in any pipeline stage.

pub fn is_bootstrap_work_empty(&self, bootstrap_keys: &HashSet<XorName>) -> bool

Check if all bootstrap-related work is done.

Returns true when none of the given bootstrap keys remain in any queue.

pub fn evict_stale(&mut self, max_age: Duration)

Evict stale pending-verification entries older than max_age.

pub fn pending_count_for_sender(&self, sender: &PeerId) -> usize

Number of pending_verify entries currently attributed to sender. Exposed for tests and observability of the per-source fairness quota.

Trait Implementations

impl Default for ReplicationQueues

fn default() -> Self

Returns the “default value” for a type.