Struct ReservoirBuffer 

pub struct ReservoirBuffer<T: Clone> { /* private fields */ }

Reservoir-sampled buffer backing the NFSP average-policy supervised dataset. Implements Vitter (1985) Algorithm R: every distinct item streamed through push is retained with probability capacity / stream_index (1-indexed across the full lifetime of the buffer). Under capacity, all pushes are kept; at capacity, each push at stream index i ≥ capacity + 1 is inserted with probability capacity / i replacing a uniformly-random existing slot.

Correctness

The key invariant Vitter’s algorithm guarantees is that at any point in time, the held items are a uniform sample of the entire stream history. This is the property NFSP needs from §3.2 — see the module doc for why FIFO would be wrong.

Determinism

The internal RNG is seedable via ReservoirBuffer::with_seed so the trainer can produce repeatable buffer trajectories under a fixed NfspConfig::seed.

Implementations

impl<T: Clone> ReservoirBuffer<T>

pub fn with_seed(capacity: usize, seed: u64) -> Self

Construct an empty reservoir with the given capacity, seeded from a fixed value for reproducible tests.

pub fn new(capacity: usize) -> Self

Construct an empty reservoir using a fresh entropy-seeded RNG.

pub fn items(&self) -> &[T]

Currently-held items.

pub fn len(&self) -> usize

Number of items currently held (≤ capacity).

pub fn is_empty(&self) -> bool

True if no items have been retained.

pub fn capacity(&self) -> usize

Maximum number of items the reservoir may hold.

pub fn stream_length(&self) -> usize

Total stream length (number of push calls observed, regardless of retention). Vitter’s i for the next incoming item is stream_length() + 1.

pub fn push(&mut self, item: T) -> bool

Push one item through the reservoir.

Under capacity: appended unconditionally. At capacity: kept with probability capacity / i (where i is the new 1-indexed stream position), replacing a uniformly-random existing slot.

Returns true if the item was retained (either appended or replaced an existing slot), false if it was discarded.

pub fn sample_with_replacement(&mut self, n: usize) -> Vec<T>

Sample n items uniformly at random with replacement from the currently-held reservoir. Returns an empty vec if the reservoir is empty.

Trait Implementations

impl<T: Clone + Clone> Clone for ReservoirBuffer<T>

fn clone(&self) -> ReservoirBuffer<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug + Clone> Debug for ReservoirBuffer<T>

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

Formats the value using the given formatter.