Skip to main content

SurbFlowEstimator

Trait SurbFlowEstimator 

Source
pub trait SurbFlowEstimator {
    // Required methods
    fn estimate_surbs_consumed(&self) -> u64;
    fn estimate_surbs_produced(&self) -> u64;

    // Provided methods
    fn estimate_surbs_evicted(&self) -> u64 { ... }
    fn estimate_surbs_refunded(&self) -> u64 { ... }
    fn saturating_diff(&self) -> u64 { ... }
    fn estimated_surb_buffer_change<E: SurbFlowEstimator>(
        &self,
        earlier: &E,
    ) -> Option<i64> { ... }
}
Expand description

Allows estimating the flow of SURBs in a Session (production or consumption).

Required Methods§

Source

fn estimate_surbs_consumed(&self) -> u64

Estimates the number of SURBs consumed.

Value returned on each call must be equal or greater to the value returned by a previous call.

Source

fn estimate_surbs_produced(&self) -> u64

Estimates the number of SURBs produced or received.

Value returned on each call must be equal or greater to the value returned by a previous call.

Provided Methods§

Source

fn estimate_surbs_evicted(&self) -> u64

Estimates the number of received SURBs the buffer evicted on overflow.

An evicted SURB has left the buffer exactly as a consumed one has; the difference is only that the full store dropped it on arrival instead of it being spent. Counting it keeps saturating_diff equal to what the buffer actually holds. Defaults to 0 for estimators that never observe eviction (the Entry, whose store does not overflow, and test mocks). Value returned on each call must be equal or greater to a previous call.

Source

fn estimate_surbs_refunded(&self) -> u64

Estimates the number of SURBs counted as consumed for a packet that then found none and was dropped, and given back.

Only saturating_diff adds these back, where a count that was never undone would hold the result one low for good. The balancer’s estimated_surb_buffer_change leaves them out: its accumulated level saturates at zero, so a count made while it was empty took nothing off it, and the refund added back would be a SURB nobody holds. Defaults to 0 for estimators whose sender gives nothing back. Value returned on each call must be equal or greater to a previous call.

Source

fn saturating_diff(&self) -> u64

Subtracts SURBs consumed and evicted from SURBs produced and given back, saturating at zero.

Consumed and evicted SURBs have both left the buffer, and a SURB given back never did, so what remains is produced + refunded - consumed - evicted – the count the buffer actually holds. Read by the PIX fill-reserve gate and the drain budget, which otherwise saw a count inflated by every SURB the full store ever evicted.

Source

fn estimated_surb_buffer_change<E: SurbFlowEstimator>( &self, earlier: &E, ) -> Option<i64>

Computes the estimated change in SURB buffer.

This is done by computing the change in produced and consumed SURBs since the earlier state and then taking their difference.

A positive result is a surplus number of SURBs added to the buffer, a negative result is a loss of SURBs from the buffer.

Evictions count as SURBs leaving the buffer alongside consumption: a tick that receives some SURBs while the full store drops others nets only what it actually retained. Without this the accumulated level drifts above the real occupancy by every SURB the store ever evicted. SURBs given back are left out; see estimate_surbs_refunded. Returns None if earlier had more SURBs produced/consumed/evicted than this instance (overflow).

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§