use parking_lot::Mutex;
use std::time::Duration;
pub const DEFAULT_EMA_ALPHA: f64 = 0.2;
pub const DEFAULT_MIN_SAMPLES: usize = 10;
pub const DEFAULT_SIGMA_MULTIPLIER: f64 = 1.0;
#[derive(Debug, Clone, Default)]
struct HedgeState {
ema_latency_ms: f64,
variance_ms2: f64,
sample_count: usize,
}
#[derive(Debug)]
pub struct HedgeController {
state: Mutex<HedgeState>,
ema_alpha: f64,
min_samples: usize,
sigma_multiplier: f64,
}
impl HedgeController {
pub fn new(ema_alpha: f64, min_samples: usize, sigma_multiplier: f64) -> Self {
assert!(
ema_alpha > 0.0 && ema_alpha <= 1.0,
"ema_alpha must be in (0, 1], got {ema_alpha}"
);
assert!(
min_samples >= 1,
"min_samples must be >= 1, got {min_samples}"
);
assert!(
sigma_multiplier > 0.0,
"sigma_multiplier must be > 0.0, got {sigma_multiplier}"
);
Self {
state: Mutex::new(HedgeState::default()),
ema_alpha,
min_samples,
sigma_multiplier,
}
}
pub fn with_defaults() -> Self {
Self::new(
DEFAULT_EMA_ALPHA,
DEFAULT_MIN_SAMPLES,
DEFAULT_SIGMA_MULTIPLIER,
)
}
pub(crate) fn record_latency(&self, latency: Duration) {
let x_ms = latency.as_secs_f64() * 1000.0;
let alpha = self.ema_alpha;
let mut state = self.state.lock();
if state.sample_count == 0 {
state.ema_latency_ms = x_ms;
state.variance_ms2 = 0.0;
state.sample_count = 1;
} else {
let ema_old = state.ema_latency_ms;
let var_old = state.variance_ms2;
let ema_new = alpha * x_ms + (1.0 - alpha) * ema_old;
let var_new =
((1.0 - alpha) * var_old + alpha * (x_ms - ema_new) * (x_ms - ema_old)).max(0.0);
state.ema_latency_ms = ema_new;
state.variance_ms2 = var_new;
state.sample_count += 1;
}
}
pub fn p84_threshold(&self) -> Option<Duration> {
let state = self.state.lock();
if state.sample_count < self.min_samples {
return None;
}
let ema_ms = state.ema_latency_ms;
let var_ms2 = state.variance_ms2;
if !ema_ms.is_finite() || !var_ms2.is_finite() || var_ms2 < 0.0 {
return None;
}
let sigma_ms = var_ms2.sqrt();
let threshold_ms = ema_ms + self.sigma_multiplier * sigma_ms;
if !threshold_ms.is_finite() || threshold_ms < 0.0 {
return None;
}
Some(Duration::from_secs_f64(threshold_ms / 1000.0))
}
pub fn should_hedge(&self, elapsed: Duration) -> bool {
match self.p84_threshold() {
Some(threshold) => elapsed > threshold,
None => false,
}
}
pub fn sample_count(&self) -> usize {
self.state.lock().sample_count
}
pub fn ema_latency(&self) -> Option<Duration> {
let state = self.state.lock();
if state.sample_count == 0 {
return None;
}
let ema_ms = state.ema_latency_ms;
if !ema_ms.is_finite() || ema_ms < 0.0 {
return None;
}
Some(Duration::from_secs_f64(ema_ms / 1000.0))
}
pub fn std_dev_ms(&self) -> Option<f64> {
let state = self.state.lock();
if state.sample_count < self.min_samples {
return None;
}
let var_ms2 = state.variance_ms2;
if !var_ms2.is_finite() || var_ms2 < 0.0 {
return None;
}
Some(var_ms2.sqrt())
}
#[allow(dead_code)]
pub(crate) fn reset(&self) {
let mut state = self.state.lock();
state.ema_latency_ms = 0.0;
state.variance_ms2 = 0.0;
state.sample_count = 0;
}
}
impl Default for HedgeController {
fn default() -> Self {
Self::with_defaults()
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::Arc;
use std::thread;
#[test]
fn with_defaults_matches_constants() {
let c = HedgeController::with_defaults();
for _ in 0..9 {
c.record_latency(Duration::from_millis(100));
}
assert_eq!(c.sample_count(), 9);
assert!(c.p84_threshold().is_none(), "below min_samples=10");
c.record_latency(Duration::from_millis(100));
assert_eq!(c.sample_count(), 10);
assert!(c.p84_threshold().is_some(), "at min_samples=10");
}
#[test]
fn default_equals_with_defaults() {
let a = HedgeController::default();
let b = HedgeController::with_defaults();
a.record_latency(Duration::from_millis(100));
b.record_latency(Duration::from_millis(100));
assert_eq!(a.sample_count(), b.sample_count());
assert_eq!(a.ema_latency(), b.ema_latency());
}
#[test]
fn new_custom_params() {
let c = HedgeController::new(0.5, 5, 2.0);
for _ in 0..4 {
c.record_latency(Duration::from_millis(100));
}
assert_eq!(c.sample_count(), 4);
assert!(c.p84_threshold().is_none(), "below custom min_samples=5");
c.record_latency(Duration::from_millis(100));
assert!(c.p84_threshold().is_some(), "at custom min_samples=5");
}
#[test]
#[should_panic(expected = "ema_alpha must be in (0, 1]")]
fn new_alpha_zero_panics() {
let _ = HedgeController::new(0.0, 10, 1.0);
}
#[test]
#[should_panic(expected = "ema_alpha must be in (0, 1]")]
fn new_alpha_above_one_panics() {
let _ = HedgeController::new(1.5, 10, 1.0);
}
#[test]
#[should_panic(expected = "min_samples must be >= 1")]
fn new_min_samples_zero_panics() {
let _ = HedgeController::new(0.2, 0, 1.0);
}
#[test]
#[should_panic(expected = "sigma_multiplier must be > 0.0")]
fn new_sigma_multiplier_zero_panics() {
let _ = HedgeController::new(0.2, 10, 0.0);
}
#[test]
fn new_alpha_one_is_valid() {
let c = HedgeController::new(1.0, 1, 1.0);
c.record_latency(Duration::from_millis(100));
let ema = c.ema_latency().unwrap();
let ema_ms = ema.as_secs_f64() * 1000.0;
assert!((ema_ms - 100.0).abs() < 0.01);
}
#[test]
fn record_first_sample_sets_ema_to_latency() {
let c = HedgeController::with_defaults();
c.record_latency(Duration::from_millis(100));
assert_eq!(c.sample_count(), 1);
assert_eq!(c.ema_latency(), Some(Duration::from_millis(100)));
}
#[test]
fn record_first_sample_variance_is_zero() {
let c = HedgeController::with_defaults();
c.record_latency(Duration::from_millis(100));
assert_eq!(c.ema_latency(), Some(Duration::from_millis(100)));
}
#[test]
fn record_two_samples_ema_converges() {
let c = HedgeController::with_defaults();
c.record_latency(Duration::from_millis(100)); c.record_latency(Duration::from_millis(200)); let ema = c.ema_latency().unwrap();
let ema_ms = ema.as_secs_f64() * 1000.0;
assert!(
(ema_ms - 120.0).abs() < 0.01,
"EMA should be 120, got {ema_ms}"
);
}
#[test]
fn record_multiple_samples_ema_weighted_average() {
let c = HedgeController::with_defaults();
for _ in 0..20 {
c.record_latency(Duration::from_millis(100));
}
let ema = c.ema_latency().unwrap();
let ema_ms = ema.as_secs_f64() * 1000.0;
assert!(
(ema_ms - 100.0).abs() < 0.5,
"EMA should converge to 100, got {ema_ms}"
);
}
#[test]
fn record_constant_samples_variance_zero() {
let c = HedgeController::with_defaults();
for _ in 0..20 {
c.record_latency(Duration::from_millis(100));
}
let sigma = c.std_dev_ms().unwrap();
assert!(sigma < 0.1, "std_dev should be near 0, got {sigma}");
}
#[test]
fn record_high_variance_samples_increases_stddev() {
let c = HedgeController::with_defaults();
for i in 0..20 {
let v = if i % 2 == 0 { 50 } else { 150 };
c.record_latency(Duration::from_millis(v));
}
let sigma = c.std_dev_ms().unwrap();
assert!(
sigma > 30.0 && sigma < 70.0,
"std_dev should be near 50, got {sigma}"
);
}
#[test]
fn p84_threshold_none_below_min_samples() {
let c = HedgeController::with_defaults();
for _ in 0..9 {
c.record_latency(Duration::from_millis(100));
}
assert_eq!(c.p84_threshold(), None);
}
#[test]
fn p84_threshold_some_at_min_samples() {
let c = HedgeController::with_defaults();
for _ in 0..10 {
c.record_latency(Duration::from_millis(100));
}
let threshold = c.p84_threshold().expect("threshold should be available");
let threshold_ms = threshold.as_secs_f64() * 1000.0;
assert!(
(threshold_ms - 100.0).abs() < 0.5,
"P84 should be 100, got {threshold_ms}"
);
}
#[test]
fn p84_threshold_equals_ema_plus_sigma_for_p84() {
let c = HedgeController::new(0.5, 2, 1.0);
c.record_latency(Duration::from_millis(100));
c.record_latency(Duration::from_millis(200));
let threshold = c.p84_threshold().expect("threshold should be available");
let threshold_ms = threshold.as_secs_f64() * 1000.0;
assert!(
(threshold_ms - 200.0).abs() < 1.0,
"P84 should be 200, got {threshold_ms}"
);
}
#[test]
fn p84_threshold_respects_sigma_multiplier() {
let c = HedgeController::new(0.5, 2, 2.0);
c.record_latency(Duration::from_millis(100));
c.record_latency(Duration::from_millis(200));
let threshold = c.p84_threshold().expect("threshold should be available");
let threshold_ms = threshold.as_secs_f64() * 1000.0;
assert!(
(threshold_ms - 250.0).abs() < 1.0,
"P84 with mult=2 should be 250, got {threshold_ms}"
);
}
#[test]
fn should_hedge_false_below_min_samples() {
let c = HedgeController::with_defaults();
for _ in 0..5 {
c.record_latency(Duration::from_millis(100));
}
assert!(!c.should_hedge(Duration::from_secs(10)));
}
#[test]
fn should_hedge_false_when_elapsed_below_threshold() {
let c = HedgeController::with_defaults();
for _ in 0..15 {
c.record_latency(Duration::from_millis(100));
}
assert!(!c.should_hedge(Duration::from_millis(50)));
}
#[test]
fn should_hedge_false_when_elapsed_equals_threshold() {
let c = HedgeController::with_defaults();
for _ in 0..15 {
c.record_latency(Duration::from_millis(100));
}
let threshold = c.p84_threshold().unwrap();
assert!(!c.should_hedge(threshold));
}
#[test]
fn should_hedge_true_when_elapsed_above_threshold() {
let c = HedgeController::with_defaults();
for _ in 0..15 {
c.record_latency(Duration::from_millis(100));
}
assert!(c.should_hedge(Duration::from_millis(200)));
}
#[test]
fn reset_clears_state() {
let c = HedgeController::with_defaults();
for _ in 0..15 {
c.record_latency(Duration::from_millis(100));
}
assert_eq!(c.sample_count(), 15);
assert!(c.p84_threshold().is_some());
c.reset();
assert_eq!(c.sample_count(), 0);
assert_eq!(c.p84_threshold(), None);
assert_eq!(c.ema_latency(), None);
}
#[test]
fn record_after_reset_treats_as_first_sample() {
let c = HedgeController::with_defaults();
for _ in 0..15 {
c.record_latency(Duration::from_millis(100));
}
c.reset();
c.record_latency(Duration::from_millis(200));
assert_eq!(c.ema_latency(), Some(Duration::from_millis(200)));
assert_eq!(c.sample_count(), 1);
}
#[test]
fn concurrent_record_latency_no_lost_updates() {
let c = Arc::new(HedgeController::new(0.2, 1, 1.0));
let thread_count = 4;
let per_thread = 100;
let mut handles = Vec::new();
for _ in 0..thread_count {
let cc = c.clone();
handles.push(thread::spawn(move || {
for _ in 0..per_thread {
cc.record_latency(Duration::from_millis(100));
}
}));
}
for h in handles {
h.join().expect("thread should not panic");
}
assert_eq!(
c.sample_count(),
thread_count * per_thread,
"Mutex should prevent lost updates"
);
}
#[test]
fn concurrent_record_then_check_threshold() {
let c = Arc::new(HedgeController::new(0.2, 5, 1.0));
let mut handles = Vec::new();
for _ in 0..4 {
let cc = c.clone();
handles.push(thread::spawn(move || {
for _ in 0..50 {
cc.record_latency(Duration::from_millis(100));
let _ = cc.p84_threshold();
let _ = cc.should_hedge(Duration::from_millis(200));
}
}));
}
for h in handles {
h.join().expect("thread should not panic");
}
assert_eq!(c.sample_count(), 200);
let threshold = c.p84_threshold().expect("threshold should be available");
let threshold_ms = threshold.as_secs_f64() * 1000.0;
assert!(
(threshold_ms - 100.0).abs() < 5.0,
"P84 should converge to ~100, got {threshold_ms}"
);
}
#[test]
fn ema_latency_none_on_empty_controller() {
let c = HedgeController::with_defaults();
assert_eq!(c.ema_latency(), None);
}
#[test]
fn std_dev_none_below_min_samples() {
let c = HedgeController::with_defaults();
c.record_latency(Duration::from_millis(100));
assert_eq!(c.std_dev_ms(), None);
}
#[test]
fn std_dev_some_at_min_samples() {
let c = HedgeController::with_defaults();
for _ in 0..10 {
c.record_latency(Duration::from_millis(100));
}
assert!(c.std_dev_ms().is_some());
}
#[test]
fn ema_reacts_to_recent_changes_faster_with_higher_alpha() {
let c = HedgeController::new(0.8, 1, 1.0);
c.record_latency(Duration::from_millis(100));
c.record_latency(Duration::from_millis(200));
let ema = c.ema_latency().unwrap();
let ema_ms = ema.as_secs_f64() * 1000.0;
assert!(
(ema_ms - 180.0).abs() < 0.5,
"EMA should be 180, got {ema_ms}"
);
}
#[test]
fn p84_increases_with_high_latency_outlier() {
let c = HedgeController::with_defaults();
for _ in 0..9 {
c.record_latency(Duration::from_millis(100));
}
c.record_latency(Duration::from_millis(1000));
let threshold = c.p84_threshold().expect("threshold");
let threshold_ms = threshold.as_secs_f64() * 1000.0;
assert!(
threshold_ms > 150.0,
"P84 should react to outlier, got {threshold_ms}"
);
}
#[test]
fn record_zero_latency_is_valid_sample() {
let c = HedgeController::with_defaults();
c.record_latency(Duration::ZERO);
assert_eq!(c.sample_count(), 1);
assert_eq!(c.ema_latency(), Some(Duration::ZERO));
}
}