Struct PacedWriter 

pub struct PacedWriter<S> {
    inner: S,
    window: WindowController,
    clock: DeliveryClock,
    supply: SurbSupply,
    deadline: Duration,
    park: Option<Pin<Box<dyn Future<Output = ()> + Send>>>,
    stalled_parks: u32,
    persist_after: u32,
    sent_total: u64,
    refreshes: u64,
}

Wraps a Session socket, admitting writes only while the [WindowController] has room against the honest delivery clock and the SURB ceiling. Reads are delegated untouched (never gated), so the duplex socket cannot deadlock; the window always keeps at least min_window_size admissible.

S is Unpin (the boxed Session socket is), so this needs no pin projection.

Fields

inner: S

window: WindowController

clock: DeliveryClock

supply: SurbSupply

deadline: Duration

Keep-progress deadline: how long to park when the window is momentarily full before re-checking, and the persist-probe interval (see stalled_parks).

park: Option<Pin<Box<dyn Future<Output = ()> + Send>>>

Pending park timer, recreated per park.

stalled_parks: u32

Consecutive keep-progress parks that saw no honest delivery and admitted no bytes. Reset to 0 on any admission or any delivery. When it reaches persist_after (> 0), the persist probe fires (see Self::admissible).

persist_after: u32

Persist-probe threshold (consecutive no-progress parks). 0 disables the probe — the default clean behaviour; a robust profile sets it (~8). Sourced from FlowControlConfig.

sent_total: u64

Cumulative bytes admitted (diagnostics).

refreshes: u64

refresh_window call counter, for throttling the diagnostic trace.

Implementations

impl<S> PacedWriter<S>

pub fn new( inner: S, cfg: FlowControlConfig, clock: DeliveryClock, supply: SurbSupply, ) -> Self

Assembles a paced writer. clock is the honest delivery clock (fed by the reliable ack tap or return bytes); supply is the SURB ceiling; cfg seeds the window.

fn refresh_window(&mut self)

Folds the latest honest delivery into the window. cwnd moves only on the honest delivery clock (up on ack, down on loss); SURB supply never touches cwnd — so a transient buffer_level dip cannot destroy the learned window (it can only clamp the effective window down via the ceiling, in Self::admissible).

fn admissible(&self) -> usize

Bytes admissible right now, against the live SURB ceiling.

Normally this is min(cwnd, surb_ceiling) − inflight: the AIMD window bounds the send rate to the drain rate, and the SURB ceiling clamps it down when supply is low (never up — invariant 2).

Persist probe (opt-in, anti-deadlock). At end-of-stream a HOPR session has no half-close, so the final frames may be acked slowly (or their retransmissions must exhaust before their bytes retire from inflight). Meanwhile inflight sits at cwnd, so the normal formula admits 0 and the writer would park forever — the tail deadlock the 5-sample measurement showed. When enabled (persist_after > 0), after that many consecutive no-progress parks we admit a bounded min_window_size beyond cwnd but still capped by the SURB ceiling. This is the classic TCP persist-timer escape, and it is invariant-safe: it never spends past the SURB ceiling (anti-grief intact), and a peer withholding acks can extract at most min_window_size per persist_after × deadline — it can only ever make us slower, never faster or over-spending. persist_after == 0 (the default) disables it entirely: the verified clean behaviour.

Trait Implementations

impl<S: AsyncRead + Unpin> AsyncRead for PacedWriter<S>

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>], ) -> Poll<Result<usize, Error>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl<S: AsyncWrite + Unpin> AsyncWrite for PacedWriter<S>

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to flush the object, ensuring that any buffered data reach their destination.

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to close the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>

Attempt to write bytes from bufs into the object using vectored IO operations.