arcium-primitives 0.6.3

pub mod buffered;
pub mod errors;
pub mod futures;

use std::fmt::Debug;

pub use buffered::{Buffer, BufferConfig, BufferedStream, PrefetchHandle, SharedBufferConfig};
pub use errors::CorrelatedStreamError;
pub use futures::{CompletionHandle, Next, NextVec, NextVecIterator, ResyncHandle};

use crate::correlated_randomness::Correlation;

/// Main abstraction interface to obtain preprocessing items.
///
/// To keep consistency, requests must be issued in the same order across all parties.
pub trait CorrelatedStream<P: Correlation>: Send {
    /// The error type returned by the generator.
    type Error: Debug + Clone + From<CorrelatedStreamError> + Send + 'static;

    /// Returns a single future that resolves to all `n_elements` items at once.
    /// Can fail if request is too large/small or if the request cannot
    /// be fulfilled by the stream for some reason.
    fn next_n(&self, n_elements: usize) -> Result<NextVec<P, Self::Error>, CorrelatedStreamError>;

    /// Proactively generates `n_elements` items into the buffer so later [`next_n`](Self::next_n)
    /// calls need not wait on generation. Fire-and-forget (proceeds whether or not the handle is
    /// awaited); does not advance [`position`](Self::position). The default is a no-op.
    fn prefetch_n(&self, _n_elements: usize) -> PrefetchHandle<Self::Error> {
        PrefetchHandle::ready(Ok(()))
    }

    /// The cumulative number of items *delivered* through [`next_n`](Self::next_n) since creation
    /// (prefetching doesn't count). Stays in sync across parties, so it can be exchanged to agree
    /// on a common resync target.
    fn position(&self) -> u64;

    /// Advances to the absolute logical `target` by discarding intervening elements (draining the
    /// buffer, then skipping at the generator if supported) — the recovery primitive for
    /// non-fatal desyncs, where every party resyncs to the agreed `max(position)`.
    ///
    /// Forward-only: `target == position()` is a no-op, `target < position()` must error with
    /// [`ResyncRewind`](CorrelatedStreamError::ResyncRewind), and a `target` beyond what the stream
    /// can reach must error with [`ResyncUnsupported`](CorrelatedStreamError::ResyncUnsupported).
    fn resync(&self, target: u64) -> ResyncHandle<Self::Error>;
}