Struct Throttler 

pub struct Throttler<T, F> { /* private fields */ }

Throttler rate limits messages by dropping or buffering them.

Throttler takes messages of type T and callback of type F for dropping or processing messages.

The throttler stores its limit and interval as non-zero values from RateLimit. Internal counters, buffers, and timer state stay private so callers can observe state without breaking rate-limit invariants.

Callback contract

The output_send and output_drop callbacks are invoked inline from Throttler::send and the drain handler. They must not reenter the throttler (for example by calling send synchronously), since the throttler mutates its buffer and window state through UnsafeCell without borrow-check protection. Route side effects through an asynchronous queue when in doubt.

Implementations

impl<T, F> Throttler<T, F>

where T: Debug,

pub fn new( rate_limit: RateLimit, clock: Rc<RefCell<dyn Clock>>, timer_name: &str, output_send: F, output_drop: Option<F>, actor_id: Ustr, ) -> Self

Creates a new Throttler instance.

The timer is registered under a name namespaced by actor_id so multiple throttlers can share one clock.

pub fn delta_next(&self) -> u64

Time delta when the next message can be sent.

Uses saturating subtraction so a clock regression or a future-dated timestamp yields a zero delta instead of panicking.

pub fn reset(&mut self)

Reset the throttler which clears internal state and cancels any pending timer so no drain or resume callback fires after reset.

impl<T, F> Throttler<T, F>

pub const fn limit(&self) -> usize

Maximum number of messages that can be sent within the interval.

pub const fn interval_ns(&self) -> u64

Interval between messages in nanoseconds.

pub const fn rate_limit(&self) -> RateLimit

Rate limit configured for this throttler.

pub fn qsize(&self) -> usize

Number of messages queued in buffer.

pub fn used(&self) -> f64

Fractional value of rate limit consumed in current interval.

pub const fn is_limiting(&self) -> bool

Whether the throttler is currently limiting the message rate.

pub const fn recv_count(&self) -> usize

Number of messages received.

pub const fn sent_count(&self) -> usize

Number of messages sent.

impl<T, F> Throttler<T, F>

where T: 'static + Debug, F: Fn(T) + 'static,

pub fn to_actor(self) -> Rc<UnsafeCell<Self>>

pub fn dispose(&mut self)

Disposes of the throttler by cancelling its timer, deregistering its process endpoint from the message bus, and removing it from the actor registry.

Call this before dropping a throttler registered via Throttler::to_actor to avoid leaking the process endpoint. For embedded throttlers (not registered) this is still safe: the endpoint and registry removals are no-ops.

pub fn try_reserve(&mut self, count: usize) -> bool

Reserves capacity for count messages without sending callbacks.

Returns false when the current window cannot accept all messages. No partial reservation is made in that case. The resume timer is armed only when the window is genuinely full (delta_next > 0); when the window already slid (delta_next == 0) the next call re-evaluates without arming a zero-delta timer that would fire immediately and log spam.

pub fn send(&mut self, msg: T)

where T: 'static, F: Fn(T) + 'static,

Trait Implementations

impl<T, F> Actor for Throttler<T, F>

where T: 'static + Debug, F: Fn(T) + 'static,

fn id(&self) -> Ustr

The unique identifier for the actor.

fn handle(&mut self, _msg: &dyn Any)

Handles the msg.

fn as_any(&self) -> &dyn Any

Returns a reference to self as Any, for downcasting support.

fn as_any_mut(&mut self) -> &mut dyn Any

where Self: Sized,

Returns a mutable reference to self as Any, for downcasting support.

impl<T, F> Debug for Throttler<T, F>

where T: Debug,

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

Formats the value using the given formatter.

impl<T, F> Drop for Throttler<T, F>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.