Struct StreamState 

pub struct StreamState { /* private fields */ }

Per-stream state for multiplexing.

Implementations

impl StreamState

pub fn new(reliable: bool) -> Self

Create a new stream state

pub fn new_with_weight(reliable: bool, fairness_weight: u8) -> Self

Create a new stream state with a fair-scheduler weight.

Uses DEFAULT_STREAM_WINDOW_BYTES for the initial credit window — auto-created receive-side streams (via get_or_create_stream) inherit the default so RxCreditState can mint grants on threshold crossings. Callers that need a specific window go through Self::new_full.

pub fn new_full(reliable: bool, fairness_weight: u8, tx_window: u32) -> Self

Create a new stream state with full config (weight + tx window). Epoch defaults to 0 (the “no epoch” sentinel used by legacy auto-create paths); sessions that go through open_stream_full allocate a fresh epoch via Self::new_full_with_epoch.

pub fn new_full_with_epoch( reliable: bool, fairness_weight: u8, tx_window: u32, epoch: u64, ) -> Self

Create a new stream state with a caller-supplied epoch.

Sessions call this via open_stream_full with a monotonic epoch; stale Stream handles / TxSlotGuards from a prior close/reopen cycle will fail the epoch check against the new state.

pub fn touch(&self)

Refresh last-activity timestamp. Called on every send and on every receive that lands packets/events into the stream.

pub fn last_activity_ns(&self) -> u64

Nanoseconds since epoch of the last activity.

pub fn reliable_mode(&self) -> bool

Reliability mode this stream was created with.

pub fn fairness_weight(&self) -> u8

Fair-scheduler weight for this stream.

pub fn epoch(&self) -> u64

Monotonic per-session epoch captured at construction time. 0 means “no epoch recorded” (legacy auto-create path).

pub fn tx_window(&self) -> u32

Configured initial credit window in bytes. 0 means “no limit” — backpressure is disabled for this stream (v1 escape hatch).

pub fn tx_credit_remaining(&self) -> u32

Current remaining send credit in bytes. Approaches 0 as the sender pushes packets without a corresponding receiver grant; the next acquire at 0 returns Backpressure.

pub fn backpressure_events(&self) -> u64

Cumulative number of Backpressure rejections since the stream opened.

pub fn credit_grants_received(&self) -> u64

Cumulative StreamWindow grants received on this stream.

pub fn credit_grants_sent(&self) -> u64

Cumulative StreamWindow grants emitted on this stream.

pub fn rx_credit(&self) -> &RxCreditState

Access the receive-side credit bookkeeping.

pub fn try_acquire_tx_credit(&self, bytes: u32) -> bool

Try to acquire bytes of send credit via a CAS loop.

Returns true on success — tx_credit_remaining is decremented and tx_bytes_sent is bumped so the authoritative-grant reconciliation sees a consistent view. Returns false when remaining credit is below bytes; caller returns StreamError::Backpressure and the rejection counter bumps.

tx_window == 0 disables the check; all requests admit and the counter is not touched.

pub fn refund_tx_credit(&self, bytes: u32)

Refund bytes of send credit. Called by TxSlotGuard::drop when a previously acquired slot never made it to the wire (socket send cancelled, early return, etc.). Rolls back both tx_credit_remaining and the tx_bytes_sent bump recorded at admission — the bytes never left the sender, so neither counter should reflect them. No clamp at tx_window: grants may have pushed the counter past the initial window, and refunding those bytes back to a tx_window ceiling would strand legitimately-granted credit.

pub fn try_rollback_tx_seq(&self, seq: u64) -> bool

Attempt to roll back a TX sequence number that was allocated via Self::next_tx_seq but whose packet never reached the wire (e.g. the FairScheduler queue was full and deliver_stream_packet returned Backpressure after the seq was consumed). Unlike the byte credit — which TxSlotGuard::drop always refunds — the seq is a monotonic fetch_add counter, so a blind decrement is unsafe: a concurrent sender on the same stream may already have consumed seq + 1, and decrementing would re-issue that sender’s sequence.

We therefore roll back only via a CAS seq + 1 -> seq, which succeeds exactly when seq was the most-recently-issued sequence (the common case for the backpressure-on-the-last-flush scenario) and no other send has advanced the counter in between. Returns true if the rollback won the CAS (no gap left behind), false if another allocation raced ahead — in which case the gap is genuinely unavoidable and the reliable-stream retransmit/NACK machinery must recover it instead.

pub fn apply_authoritative_grant(&self, total_consumed: u64)

Apply a receiver grant reporting the receiver’s absolute cumulative consumed-byte count on this stream. Monotonic — grants arriving with total_consumed below the already-observed maximum are treated as stale duplicates and only bump the credit_grants_received counter. Self-healing: a single lost grant is reconciled by the next one because each grant carries the receiver’s full accounting.

Reconciliation adds the delta of newly-acknowledged bytes (total_consumed - prev_max_consumed) to tx_credit_remaining via fetch_update. The additive form composes atomically with the CAS in try_acquire_tx_credit and the fetch_update in refund_tx_credit: every operation preserves the invariant remaining + (sent - max_consumed) == window regardless of interleaving. An earlier .store()-based implementation recomputed from a racy snapshot of tx_bytes_sent, which could silently overwrite a concurrent acquire’s CAS result.

pub fn tx_bytes_sent(&self) -> u64

Cumulative bytes committed to the wire on this stream. Admission bumps it; uncommitted-guard drops roll it back.

pub fn max_consumed_seen(&self) -> u64

Highest total_consumed this sender has observed from the receiver on this stream. Monotonic.

pub fn on_bytes_consumed(&self, bytes: u64) -> Option<u64>

Record that the receiver side has accepted bytes off the wire on this stream. Returns Some(total_consumed) — the receiver’s new cumulative consumed count — so the caller can emit an authoritative StreamWindow grant. Returns None when receive-side bookkeeping is disabled (window_bytes == 0).

pub fn note_grant_sent(&self)

Increment the “grants emitted” counter. Called after a grant packet has been successfully handed to the socket send path.

pub fn next_tx_seq(&self) -> u64

Get and increment the TX sequence number. Refreshes last_activity.

pub fn current_tx_seq(&self) -> u64

Get the current TX sequence number

pub fn update_rx_seq(&self, seq: u64)

Update the RX sequence number. Refreshes last_activity.

pub fn current_rx_seq(&self) -> u64

Get the current RX sequence number

pub fn with_reliability<F, R>(&self, f: F) -> R

where F: FnOnce(&mut Box<dyn ReliabilityMode>) -> R,

Access the reliability mode

pub fn push_event(&self, event: StoredEvent)

Push an event to the inbound queue

pub fn pop_event(&self) -> Option<StoredEvent>

Pop an event from the inbound queue

pub fn inbound_len(&self) -> usize

Get the number of pending inbound events

pub fn is_active(&self) -> bool

Check if stream is active

pub fn deactivate(&self)

Deactivate the stream

Trait Implementations

impl Debug for StreamState

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

Formats the value using the given formatter.