use std::future::Future;
use std::num::NonZeroUsize;
use std::sync::Arc;
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::{Duration, SystemTime};
use tokio::sync::{Semaphore, mpsc};
use tokio::time::{Instant, sleep_until, timeout};
use crate::executor::Executor;
use crate::outcome::{ErrorKind, Outcome, Sample};
use crate::schedule::{Rate, Schedule};
use crate::stats::Recorder;
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct LoadConfig {
pub rate: Rate,
pub duration: Duration,
pub concurrency: NonZeroUsize,
pub timeout: Duration,
}
#[derive(Debug)]
pub struct Engine<E> {
config: LoadConfig,
executor: Arc<E>,
progress: Progress,
}
impl<E: Executor> Engine<E> {
pub fn new(config: LoadConfig, executor: E) -> Self {
Self {
config,
executor: Arc::new(executor),
progress: Progress::default(),
}
}
#[must_use]
pub fn progress(&self) -> Progress {
self.progress.clone()
}
pub async fn run(self) -> Measurements {
self.run_until(std::future::pending()).await
}
#[allow(
clippy::missing_panics_doc,
reason = "the expects guard internal invariants, not caller input"
)]
pub async fn run_until(self, shutdown: impl Future<Output = ()>) -> Measurements {
let Self {
config,
executor,
progress,
} = self;
let schedule = Schedule::new(config.rate, config.duration);
let semaphore = Arc::new(Semaphore::new(config.concurrency.get()));
let (samples_tx, mut samples_rx) = mpsc::unbounded_channel::<Sample>();
let collector = tokio::spawn(async move {
let mut recorder = Recorder::new();
while let Some(sample) = samples_rx.recv().await {
recorder.record(&sample);
}
recorder
});
let started_at = SystemTime::now();
let start = Instant::now();
let deadline = sleep_until(start + config.duration);
tokio::pin!(shutdown, deadline);
let mut sent: u64 = 0;
let interrupted = loop {
if sent == schedule.len() {
break false;
}
let intended = start + schedule.offset(sent);
tokio::select! {
biased;
() = &mut shutdown => break true,
() = sleep_until(intended) => {}
}
let permit = if let Ok(permit) = Arc::clone(&semaphore).try_acquire_owned() {
permit
} else {
tokio::select! {
biased;
() = &mut shutdown => break true,
() = &mut deadline => break false,
permit = Arc::clone(&semaphore).acquire_owned() => {
permit.expect("the semaphore is never closed")
}
}
};
let sent_at = Instant::now();
let executor = Arc::clone(&executor);
let samples_tx = samples_tx.clone();
let progress = progress.clone();
let request_timeout = config.timeout;
progress.0.sent.fetch_add(1, Ordering::Relaxed);
tokio::spawn(async move {
let outcome = timeout(request_timeout, executor.execute())
.await
.unwrap_or(Outcome::Error(ErrorKind::Timeout));
let completed_at = Instant::now();
drop(permit);
progress.record_completion(outcome);
let _ = samples_tx.send(Sample {
latency: completed_at - intended,
send_lag: sent_at - intended,
outcome,
});
});
sent += 1;
};
let send_window = if interrupted {
start.elapsed()
} else {
start.elapsed().max(config.duration)
};
drop(samples_tx);
let recorder = collector.await.expect("the collector task does not panic");
Measurements {
config,
scheduled: schedule.len(),
sent,
send_window,
elapsed: start.elapsed(),
interrupted,
started_at,
recorder,
}
}
}
#[derive(Debug, Clone)]
pub struct Measurements {
pub config: LoadConfig,
pub scheduled: u64,
pub sent: u64,
pub send_window: Duration,
pub elapsed: Duration,
pub interrupted: bool,
pub started_at: SystemTime,
pub(crate) recorder: Recorder,
}
impl Measurements {
#[must_use]
pub fn unsent(&self) -> u64 {
if self.interrupted {
let due =
Schedule::new(self.config.rate, self.config.duration).due_by(self.send_window);
due.saturating_sub(self.sent)
} else {
self.scheduled - self.sent
}
}
}
#[derive(Debug, Clone, Default)]
pub struct Progress(Arc<Counters>);
#[derive(Debug, Default)]
struct Counters {
sent: AtomicU64,
completed: AtomicU64,
failures: AtomicU64,
}
impl Progress {
fn record_completion(&self, outcome: Outcome) {
self.0.completed.fetch_add(1, Ordering::Relaxed);
if outcome.is_failure() {
self.0.failures.fetch_add(1, Ordering::Relaxed);
}
}
#[must_use]
pub fn snapshot(&self) -> ProgressSnapshot {
let completed = self.0.completed.load(Ordering::Relaxed);
let failures = self.0.failures.load(Ordering::Relaxed);
let sent = self.0.sent.load(Ordering::Relaxed);
ProgressSnapshot {
sent,
completed,
failures,
}
}
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct ProgressSnapshot {
pub sent: u64,
pub completed: u64,
pub failures: u64,
}
impl ProgressSnapshot {
#[must_use]
pub fn in_flight(&self) -> u64 {
self.sent.saturating_sub(self.completed)
}
}
#[cfg(test)]
mod tests {
use super::*;
const OK: Outcome = Outcome::Response { status: 200 };
fn config(rps: f64, secs: u64, concurrency: usize) -> LoadConfig {
LoadConfig {
rate: Rate::per_second(rps).unwrap(),
duration: Duration::from_secs(secs),
concurrency: NonZeroUsize::new(concurrency).unwrap(),
timeout: Duration::from_secs(30),
}
}
fn ms(us: u64) -> f64 {
us as f64 / 1_000.0
}
struct FreezingTarget {
created: Instant,
base: Duration,
stall_from: Duration,
stall_until: Duration,
}
impl FreezingTarget {
fn new(base: Duration, stall_from: Duration, stall_until: Duration) -> Self {
Self {
created: Instant::now(),
base,
stall_from,
stall_until,
}
}
}
impl Executor for FreezingTarget {
async fn execute(&self) -> Outcome {
let now = self.created.elapsed();
if (self.stall_from..self.stall_until).contains(&now) {
sleep_until(self.created + self.stall_until).await;
}
tokio::time::sleep(self.base).await;
OK
}
}
struct Fixed(Duration);
impl Executor for Fixed {
async fn execute(&self) -> Outcome {
tokio::time::sleep(self.0).await;
OK
}
}
#[tokio::test(start_paused = true)]
async fn sends_the_scheduled_load_regardless_of_response_time() {
let engine = Engine::new(config(100.0, 2, 1_000), Fixed(Duration::from_millis(100)));
let m = engine.run().await;
assert_eq!(m.scheduled, 200);
assert_eq!(m.sent, 200);
assert_eq!(m.unsent(), 0);
assert_eq!(m.send_window, Duration::from_secs(2));
assert_eq!(m.recorder.completed(), 200);
assert_eq!(
m.recorder.send_lag().max(),
1,
"nothing should be sent late"
);
let p50 = ms(m.recorder.latency().value_at_quantile(0.5));
assert!((99.0..=101.0).contains(&p50), "p50 was {p50} ms");
}
#[tokio::test(start_paused = true)]
async fn a_stall_is_reflected_in_the_tail_when_concurrency_is_unbounded() {
let target = FreezingTarget::new(
Duration::from_millis(1),
Duration::from_secs(2),
Duration::from_secs(4),
);
let m = Engine::new(config(100.0, 10, 10_000), target).run().await;
let latency = m.recorder.latency();
assert_eq!(m.recorder.completed(), 1_000);
let p90 = ms(latency.value_at_quantile(0.90));
assert!((990.0..=1_020.0).contains(&p90), "p90 was {p90} ms");
let p99 = ms(latency.value_at_quantile(0.99));
assert!((1_890.0..=1_920.0).contains(&p99), "p99 was {p99} ms");
let max = ms(latency.max());
assert!((2_000.0..=2_010.0).contains(&max), "max was {max} ms");
}
#[tokio::test(start_paused = true)]
async fn a_stall_is_reflected_in_the_tail_when_concurrency_is_exhausted() {
let target = FreezingTarget::new(
Duration::from_millis(1),
Duration::from_secs(1),
Duration::from_secs(2),
);
let m = Engine::new(config(100.0, 10, 1), target).run().await;
let latency = m.recorder.latency();
assert_eq!(m.sent, 1_000, "the backlog is caught up after the stall");
let p95 = ms(latency.value_at_quantile(0.95));
assert!(p95 > 400.0, "p95 was {p95} ms");
let p99 = ms(latency.value_at_quantile(0.99));
assert!(p99 > 850.0, "p99 was {p99} ms");
let lag_p99 = ms(m.recorder.send_lag().value_at_quantile(0.99));
assert!(lag_p99 > 850.0, "send lag p99 was {lag_p99} ms");
let wire_p99 = p99 - lag_p99;
assert!(wire_p99 < 50.0, "wire time p99 was {wire_p99} ms");
}
#[tokio::test(start_paused = true)]
async fn timer_granularity_does_not_drop_requests_due_before_the_deadline() {
let m = Engine::new(config(3_000.0, 1, 1_000), Fixed(Duration::from_millis(1)))
.run()
.await;
assert_eq!(m.scheduled, 3_000);
assert_eq!(m.sent, 3_000);
assert_eq!(m.unsent(), 0);
}
#[tokio::test(start_paused = true)]
async fn requests_that_could_not_be_sent_are_reported_as_unsent() {
let m = Engine::new(config(10.0, 5, 2), Fixed(Duration::from_secs(1)))
.run()
.await;
assert_eq!(m.scheduled, 50);
assert_eq!(m.sent, 10);
assert_eq!(m.unsent(), 40);
assert_eq!(m.send_window, Duration::from_secs(5));
}
#[tokio::test(start_paused = true)]
async fn timeouts_are_errors_with_latency_from_the_intended_time() {
let mut cfg = config(10.0, 1, 100);
cfg.timeout = Duration::from_millis(250);
let m = Engine::new(cfg, Fixed(Duration::from_secs(10))).run().await;
assert_eq!(m.recorder.errors()[&ErrorKind::Timeout], 10);
assert_eq!(m.recorder.failures(), 10);
let max = ms(m.recorder.latency().max());
assert!((250.0..=251.0).contains(&max), "max was {max} ms");
assert!(m.elapsed <= Duration::from_millis(900 + 251));
}
#[tokio::test(start_paused = true)]
async fn shutdown_stops_sending_and_drains_in_flight_requests() {
let engine = Engine::new(config(100.0, 60, 1_000), Fixed(Duration::from_millis(50)));
let progress = engine.progress();
let m = engine
.run_until(tokio::time::sleep(Duration::from_secs(1)))
.await;
assert!(m.interrupted);
assert_eq!(m.sent, 100);
assert_eq!(m.unsent(), 1, "the request due exactly at 1 s");
assert_eq!(m.recorder.completed(), 100);
let snapshot = progress.snapshot();
assert_eq!(snapshot.sent, 100);
assert_eq!(snapshot.completed, 100);
assert_eq!(snapshot.in_flight(), 0);
}
}