Struct mysteriouspants_throttle::Throttle

pub struct Throttle<TArg> { /* fields omitted */ }

A simple configurable throttle for slowing down code, a little struct holding some state.

Methods

impl<TArg> Throttle<TArg>

pub fn new_variable_throttle<TDelayCalculator: Fn(TArg, Duration) -> Duration + 'static + Send + Sync>(     delay_calculator: TDelayCalculator ) -> Throttle<TArg>

Creates a new Throttle with a variable delay controlled by a closure. delay_calculator itself is an interesting type, any closure which satisfies Fn(TArg, Duration) -> Duration.

This lambda is called to determine the duration between iterations of your code.

|TArg, Duration| -> Duration
  |      |             |
  |      |             |
  |      |             v
  |      |    Duration that ought to have elapsed between calls
  |      |    to acquire. If the Duration you return is less
  |      |    than the Duration passed to you, or is zero, that
  |      |    means that no additional time will to be waited.
  |      |
  |      +--> The time since the previous call to acquire and now.
  |
  |           An argument passed through from the call to acquire.
  +---------> You can use this to change the behavior of your
              Throttle based on conditions in your calling code.

Expressed differently, on the axis of time,

  /------------lambda return--------------------\
  /----duration arg-----\                       |
 +-----------------------------------------------+
 ^                       ^\------additional-----/
 |                       |       time waited
 |                       |
 previous call           acquire called
 to acquire

An example use of a variable-rate throttle might be to wait different periods of time depending on whether your program is in backpressure, so "ease up" on your downstream call rate, so to speak.

let mut throttle = Throttle::new_variable_throttle(
    |in_backpressure: bool, time_since_previous_acquire: Duration|
        match in_backpressure {
            true => Duration::from_millis(210),
            false => Duration::from_millis(110)
        });

// the first one is free!
throttle.acquire(false);

let start_nopressure = Instant::now();
throttle.acquire(false);
assert_eq!(start_nopressure.elapsed().as_secs() == 0, true);
assert_eq!(start_nopressure.elapsed().subsec_nanos() >= 100_000_000, true);

let start_yespressure = Instant::now();
throttle.acquire(true);
assert_eq!(start_yespressure.elapsed().as_secs() == 0, true);
assert_eq!(start_yespressure.elapsed().subsec_nanos() >= 200_000_000, true);

pub fn new_tps_throttle(tps: f32) -> Throttle<TArg>

Creates a new Throttle with a constant delay of tps^-1 · 1000 ms, or tps-transactions per second.

let mut throttle = Throttle::new_tps_throttle(0.9);

// the first one is free!
throttle.acquire(());

let start = Instant::now();
throttle.acquire(());
assert_eq!(start.elapsed().as_secs() == 1, true);

pub fn acquire(&mut self, arg: TArg)

Acquires the throttle, waiting (sleeping the current thread) until enough time has passed for the running code to be at or slower than the throttle allows. The first call to acquire will never wait because there has been an undefined or arguably infinite amount of time from the previous time acquire was called. The argument arg is passed to the closure governing the wait time.