Struct PacedSink 

pub struct PacedSink<S, C = ()> { /* private fields */ }

Available on crate feature std only.

A Sink combinator that paces the items sent through it against a token bucket: the go-to way to rate datagram flows.

Wrap any framed sink — e.g. a ConnectedUdpFramed, a UdpFramed or a unix datagram codec — and every item’s cost (its byte length, by default: see DatagramCost) is paid from the budget:

• Sink::start_send never blocks an item: its cost is recorded as debt;
• Sink::poll_ready repays outstanding debt (waiting on the bucket as needed) before accepting the next item.

The long-run rate is exact, with at most one item of overshoot — the right semantics for pacing, as a datagram is atomic. Sending items larger than the burst capacity is fine: their debt is repaid in burst-sized chunks.

Stream is passed through, so a duplex frame transport stays bridgeable (e.g. via StreamForwardService) after wrapping.

To pace items-per-second rather than bytes-per-second, price every item at one unit via PacedSink::with_cost_fn.

Implementations

impl<S> PacedSink<S>

pub fn new(sink: S, rate: Rate) -> PacedSink<S>

Create a new PacedSink pacing at the given Rate, with a burst capacity of one period worth of units.

pub fn with_limiter(sink: S, limiter: RateLimiter) -> PacedSink<S>

Create a new PacedSink pacing against a caller-provided RateLimiter: clones of the handle share one aggregate budget (e.g. an egress cap across many flows).

pub fn with_burst(self, burst: u64) -> PacedSink<S>

Override the burst capacity (default: one period worth of units).

This rebuilds the sink’s own RateLimiter: any previously shared budget handle is disconnected.

pub fn set_burst(&mut self, burst: u64) -> &mut PacedSink<S>

Override the burst capacity (default: one period worth of units).

This rebuilds the sink’s own RateLimiter: any previously shared budget handle is disconnected.

impl<S, C> PacedSink<S, C>

pub fn with_cost_fn<F>(self, cost_fn: F) -> PacedSink<S, CostFn<F>>

Price items with the given function instead of their DatagramCost.

E.g. |_| 1 paces items-per-second rather than bytes-per-second.

pub fn limiter(&self) -> &RateLimiter

The RateLimiter enforcing this sink’s budget (clone it to share the budget elsewhere).

pub fn into_inner(self) -> S

Consume this combinator, returning the underlying sink.

pub fn get_ref(&self) -> &S

Get a reference to the underlying sink.

Trait Implementations

impl<S, C> Debug for PacedSink<S, C>

where S: Debug, C: Debug,

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

Formats the value using the given formatter.

impl<S, I, C> Sink<I> for PacedSink<S, C>

where S: Sink<I>, C: ItemCost<I>,

type Error = <S as Sink<I>>::Error

The type of value produced by the sink when an error occurs.

fn poll_ready( self: Pin<&mut PacedSink<S, C>>, cx: &mut Context<'_>, ) -> Poll<Result<(), <PacedSink<S, C> as Sink<I>>::Error>>

Attempts to prepare the Sink to receive a value.

fn start_send( self: Pin<&mut PacedSink<S, C>>, item: I, ) -> Result<(), <PacedSink<S, C> as Sink<I>>::Error>

Begin the process of sending a value to the sink. Each call to this function must be preceded by a successful call to poll_ready which returned Poll::Ready(Ok(())).

fn poll_flush( self: Pin<&mut PacedSink<S, C>>, cx: &mut Context<'_>, ) -> Poll<Result<(), <PacedSink<S, C> as Sink<I>>::Error>>

Flush any remaining output from this sink.

fn poll_close( self: Pin<&mut PacedSink<S, C>>, cx: &mut Context<'_>, ) -> Poll<Result<(), <PacedSink<S, C> as Sink<I>>::Error>>

Flush any remaining output and close this sink, if necessary.

impl<S, C> Stream for PacedSink<S, C>

where S: Stream,

type Item = <S as Stream>::Item

Values yielded by the stream.

fn poll_next( self: Pin<&mut PacedSink<S, C>>, cx: &mut Context<'_>, ) -> Poll<Option<<PacedSink<S, C> as Stream>::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.

impl<'__pin, S, C> Unpin for PacedSink<S, C>

where <PinnedFieldsOfHelperStruct<__Origin<'__pin, S, C>> as PinnedFieldsOfHelperTrait>::Actual: Unpin,