use core::future::Future;
use core::pin::Pin;
use core::task::{Context, Poll};
use happenstance_core::{AppendError, SequencePosition};
const SEED_CHUNK: usize = 64;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct BenchmarkParams {
batch_size: usize,
contenders: usize,
replay_events: usize,
}
impl BenchmarkParams {
pub const SMOKE: Self = Self {
batch_size: 8,
contenders: 4,
replay_events: 16,
};
#[must_use]
pub const fn new(batch_size: usize, contenders: usize, replay_events: usize) -> Self {
assert!(
batch_size > 0,
"`batch_size` must be at least one: an empty batch is refused by the \
contract before the condition is evaluated, so a benchmark of one \
measures the error path and calls it throughput"
);
assert!(
contenders > 0,
"`contenders` must be at least one: a contended append with no \
contenders measures no contention"
);
assert!(
replay_events > 0,
"`replay_events` must be at least one: a replay of nothing measures \
nothing"
);
Self {
batch_size,
contenders,
replay_events,
}
}
#[must_use]
pub const fn batch_size(self) -> usize {
self.batch_size
}
#[must_use]
pub const fn contenders(self) -> usize {
self.contenders
}
#[must_use]
pub const fn replay_events(self) -> usize {
self.replay_events
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Outcome {
Committed,
Rejected,
Refused,
Failed,
}
impl Outcome {
const fn of_error<E>(error: &AppendError<E>) -> Self {
match error {
AppendError::ConditionViolated(_) => Self::Rejected,
AppendError::ExceedsStoreLimit { .. } => Self::Refused,
_ => Self::Failed,
}
}
fn of_append<E>(result: &Result<SequencePosition, AppendError<E>>) -> Self {
match result {
Ok(_) => Self::Committed,
Err(error) => Self::of_error(error),
}
}
const fn is_committed(self) -> bool {
matches!(self, Self::Committed)
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BenchmarkPass {
label: &'static str,
attempts: usize,
committed: usize,
rejected: usize,
refused: usize,
failed: usize,
events: usize,
}
impl BenchmarkPass {
const fn new(label: &'static str) -> Self {
Self {
label,
attempts: 0,
committed: 0,
rejected: 0,
refused: 0,
failed: 0,
events: 0,
}
}
fn count(&mut self, outcome: Outcome, events: usize) {
self.attempts += 1;
match outcome {
Outcome::Committed => self.committed += 1,
Outcome::Rejected => self.rejected += 1,
Outcome::Refused => self.refused += 1,
Outcome::Failed => self.failed += 1,
}
self.events += events;
}
#[must_use]
pub const fn label(&self) -> &'static str {
self.label
}
#[must_use]
pub const fn attempts(&self) -> usize {
self.attempts
}
#[must_use]
pub const fn committed(&self) -> usize {
self.committed
}
#[must_use]
pub const fn rejected(&self) -> usize {
self.rejected
}
#[must_use]
pub const fn refused(&self) -> usize {
self.refused
}
#[must_use]
pub const fn failed(&self) -> usize {
self.failed
}
#[must_use]
pub const fn events(&self) -> usize {
self.events
}
#[must_use]
pub const fn is_well_formed(&self) -> bool {
self.attempts == self.committed + self.rejected + self.refused + self.failed
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[must_use]
pub struct BenchmarkRecord {
scenario: &'static str,
owed: &'static [&'static str],
passes: Vec<BenchmarkPass>,
}
impl BenchmarkRecord {
const fn new(scenario: &'static str, owed: &'static [&'static str]) -> Self {
Self {
scenario,
owed,
passes: Vec::new(),
}
}
fn push(&mut self, pass: BenchmarkPass) {
assert!(
self.owed.contains(&pass.label),
"{}: pushed a `{}` pass the scenario does not declare. Its owed \
labels are {:?}, and a pass outside them is a record that no \
longer says what completion means for this scenario.",
self.scenario,
pass.label,
self.owed
);
self.passes.push(pass);
}
#[must_use]
pub const fn scenario(&self) -> &'static str {
self.scenario
}
#[must_use]
pub fn passes(&self) -> &[BenchmarkPass] {
&self.passes
}
#[must_use]
pub fn pass(&self, label: &str) -> Option<&BenchmarkPass> {
self.passes.iter().find(|pass| pass.label == label)
}
#[must_use]
pub fn is_well_formed(&self) -> bool {
!self.passes.is_empty() && self.passes.iter().all(BenchmarkPass::is_well_formed)
}
#[must_use]
pub fn is_complete(&self) -> bool {
self.missing_passes().is_empty()
}
fn missing_passes(&self) -> Vec<&'static str> {
self.owed
.iter()
.copied()
.filter(|label| self.pass(label).is_none())
.collect()
}
#[must_use]
pub fn summary(&self) -> String {
self.passes
.iter()
.map(|pass| {
format!(
"{} attempts={} committed={} rejected={} refused={} failed={} events={}",
pass.label,
pass.attempts,
pass.committed,
pass.rejected,
pass.refused,
pass.failed,
pass.events
)
})
.collect::<Vec<_>>()
.join("; ")
}
pub fn report(self, scenario: &str) {
assert!(
self.is_well_formed(),
"{scenario}: every pass must report at least one attempt and account \
for each of them as committed, rejected, refused or failed. Got {self:?}"
);
let missing = self.missing_passes();
assert!(
missing.is_empty(),
"{scenario}: did not complete — the {missing:?} pass(es) it owes are \
absent rather than zero, so the run measured something other than \
what this scenario names. This is not a threshold and not a \
timing: a pass that never ran is not a slow pass. Got {self:?}"
);
println!("BENCH {scenario}: {}", self.summary());
}
}
type ContenderFuture<'a> = Pin<Box<dyn Future<Output = Outcome> + 'a>>;
struct Interleaved<'a> {
pending: Vec<Option<ContenderFuture<'a>>>,
done: Vec<Option<Outcome>>,
}
impl<'a> Interleaved<'a> {
fn new(futures: Vec<ContenderFuture<'a>>) -> Self {
let done = std::vec![None; futures.len()];
Self {
pending: futures.into_iter().map(Some).collect(),
done,
}
}
}
impl Future for Interleaved<'_> {
type Output = Vec<Outcome>;
fn poll(self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Self::Output> {
let this = self.get_mut();
let mut outstanding = false;
for (index, slot) in this.pending.iter_mut().enumerate() {
if let Some(future) = slot.as_mut() {
match future.as_mut().poll(context) {
Poll::Ready(outcome) => {
this.done[index] = Some(outcome);
*slot = None;
}
Poll::Pending => outstanding = true,
}
}
}
if outstanding {
return Poll::Pending;
}
Poll::Ready(this.done.iter().copied().flatten().collect())
}
}
pub mod scenarios {
use happenstance_core::{Event, EventStore, Query, ReadOptions, collect};
use super::{
BenchmarkParams, BenchmarkPass, BenchmarkRecord, ContenderFuture, Interleaved, Outcome,
SEED_CHUNK,
};
use crate::Fixture;
use crate::fixtures::{condition_after, query_of, query_tagged, tagged_event};
pub async fn append_throughput<F: Fixture>(
open: impl AsyncFn() -> F,
params: BenchmarkParams,
) -> BenchmarkRecord {
let fixture = open().await;
let store = fixture.connect().await;
let batch: Vec<Event> = (0..params.batch_size())
.map(|_| tagged_event("BenchmarkAppended", &[("bench", "append")]))
.collect();
let mut pass = BenchmarkPass::new("append");
if F::MAX_EVENTS_PER_BATCH.is_some_and(|ceiling| ceiling < params.batch_size()) {
pass.count(Outcome::Refused, 0);
} else {
let outcome = Outcome::of_append(&store.append(&batch, None).await);
let landed = if outcome.is_committed() {
params.batch_size()
} else {
0
};
pass.count(outcome, landed);
}
let mut record = BenchmarkRecord::new("append_throughput", &["append"]);
record.push(pass);
record
}
pub async fn conditional_append_under_contention<F: Fixture>(
open: impl AsyncFn() -> F,
params: BenchmarkParams,
) -> BenchmarkRecord {
let fixture = open().await;
let mut record =
BenchmarkRecord::new("conditional_append_under_contention", &["seed", "contend"]);
let opener = fixture.connect().await;
let boundary_event = [tagged_event("BenchmarkBoundary", &[("bench", "contend")])];
let planted = opener.append(&boundary_event, None).await;
let mut seed_pass = BenchmarkPass::new("seed");
let outcome = Outcome::of_append(&planted);
seed_pass.count(outcome, usize::from(outcome.is_committed()));
record.push(seed_pass);
let Ok(boundary) = planted else {
return record;
};
let condition = condition_after(
query_of(&["BenchmarkContender"], &[("bench", "contend")]),
boundary.get(),
);
let contender_event = [tagged_event("BenchmarkContender", &[("bench", "contend")])];
let mut stores = Vec::with_capacity(params.contenders());
for _ in 0..params.contenders() {
stores.push(fixture.connect().await);
}
let futures: Vec<ContenderFuture<'_>> = stores
.iter()
.map(|store| {
let condition = &condition;
let events = &contender_event;
let attempt =
async move { Outcome::of_append(&store.append(events, Some(condition)).await) };
Box::pin(attempt) as ContenderFuture<'_>
})
.collect();
let mut pass = BenchmarkPass::new("contend");
for outcome in Interleaved::new(futures).await {
pass.count(outcome, usize::from(outcome.is_committed()));
}
record.push(pass);
record
}
pub async fn replay_with_and_without_a_tag_filter<F: Fixture>(
open: impl AsyncFn() -> F,
params: BenchmarkParams,
) -> BenchmarkRecord {
let fixture = open().await;
let store = fixture.connect().await;
let mut record = BenchmarkRecord::new(
"replay_with_and_without_a_tag_filter",
&["seed", "replay-all", "replay-tagged"],
);
let chunk_size = F::MAX_EVENTS_PER_BATCH
.map_or(SEED_CHUNK, |ceiling| ceiling.min(SEED_CHUNK))
.max(1);
let mut seed_pass = BenchmarkPass::new("seed");
let mut written = 0usize;
while written < params.replay_events() {
let take = chunk_size.min(params.replay_events() - written);
let chunk: Vec<Event> = (0..take)
.map(|offset| seed_event(written + offset))
.collect();
let outcome = Outcome::of_append(&store.append(&chunk, None).await);
let landed = if outcome.is_committed() { take } else { 0 };
seed_pass.count(outcome, landed);
written += landed;
if !outcome.is_committed() {
break;
}
}
record.push(seed_pass);
record.push(replay(&store, "replay-all", &Query::all()).await);
record.push(replay(&store, "replay-tagged", &query_tagged(&[("shard", "hot")])).await);
record
}
fn seed_event(index: usize) -> Event {
if index.is_multiple_of(3) {
tagged_event(
"BenchmarkReplayed",
&[("bench", "replay"), ("shard", "hot")],
)
} else {
tagged_event("BenchmarkReplayed", &[("bench", "replay")])
}
}
async fn replay<S: EventStore>(store: &S, label: &'static str, query: &Query) -> BenchmarkPass {
let mut pass = BenchmarkPass::new(label);
match collect(store.read(query, ReadOptions::new())).await {
Ok(events) => pass.count(Outcome::Committed, events.len()),
Err(_) => pass.count(Outcome::Failed, 0),
}
pass
}
}
#[macro_export]
macro_rules! for_each_event_store_benchmark {
($($callback:tt)+) => {
$($callback)+! {
append_throughput,
conditional_append_under_contention,
replay_with_and_without_a_tag_filter,
}
};
}
#[doc(hidden)]
#[macro_export]
macro_rules! __emit_benchmark_tokio {
($($name:ident),* $(,)?) => {
$(
#[tokio::test]
async fn $name() {
$crate::__private::benchmark_scenarios::$name(__benchmark_fixture, __benchmark_params())
.await
.report(::core::stringify!($name));
}
)*
};
}
#[doc(hidden)]
#[macro_export]
macro_rules! __emit_benchmark_blocking {
($($name:ident),* $(,)?) => {
$(
#[test]
fn $name() {
$crate::__private::block_on(
$crate::__private::benchmark_scenarios::$name(__benchmark_fixture, __benchmark_params())
)
.report(::core::stringify!($name));
}
)*
};
}
#[macro_export]
macro_rules! event_store_benchmarks {
(
mod_name = $mod_name:ident,
emit = $emit:path,
params = $params:expr,
fixture = $fixture:expr
) => {
mod $mod_name {
#![allow(clippy::unwrap_used, unused_imports)]
use super::*;
async fn __benchmark_fixture() -> impl $crate::__private::Fixture {
$fixture
}
fn __benchmark_params() -> $crate::__private::BenchmarkParams {
$params
}
$crate::for_each_event_store_benchmark!($emit);
}
};
(mod_name = $mod_name:ident, emit = $emit:path, fixture = $fixture:expr) => {
$crate::event_store_benchmarks!(
mod_name = $mod_name,
emit = $emit,
params = $crate::__private::BenchmarkParams::SMOKE,
fixture = $fixture
);
};
(mod_name = $mod_name:ident, params = $params:expr, fixture = $fixture:expr) => {
$crate::event_store_benchmarks!(
mod_name = $mod_name,
emit = $crate::__emit_benchmark_tokio,
params = $params,
fixture = $fixture
);
};
(mod_name = $mod_name:ident, fixture = $fixture:expr) => {
$crate::event_store_benchmarks!(
mod_name = $mod_name,
emit = $crate::__emit_benchmark_tokio,
params = $crate::__private::BenchmarkParams::SMOKE,
fixture = $fixture
);
};
($fixture:expr) => {
$crate::event_store_benchmarks!(
mod_name = dcb_benchmarks,
emit = $crate::__emit_benchmark_tokio,
params = $crate::__private::BenchmarkParams::SMOKE,
fixture = $fixture
);
};
}
#[cfg(test)]
mod tests {
use super::{BenchmarkParams, BenchmarkPass, BenchmarkRecord, Outcome};
#[test]
fn a_pass_accounts_for_every_attempt() {
let mut pass = BenchmarkPass::new("contend");
pass.count(Outcome::Committed, 1);
pass.count(Outcome::Rejected, 0);
pass.count(Outcome::Failed, 0);
assert!(pass.is_well_formed());
assert_eq!(pass.attempts(), 3);
assert_eq!(pass.committed(), 1);
assert_eq!(pass.rejected(), 1);
assert_eq!(pass.failed(), 1);
assert_eq!(pass.refused(), 0);
assert_eq!(pass.events(), 1);
}
#[test]
fn an_empty_record_is_not_well_formed() {
let record = BenchmarkRecord::new("append_throughput", &["append"]);
assert!(!record.is_well_formed());
}
#[test]
fn a_summary_is_one_line() {
let mut record = BenchmarkRecord::new(
"replay_with_and_without_a_tag_filter",
&["seed", "replay-all", "replay-tagged"],
);
let mut first = BenchmarkPass::new("replay-all");
first.count(Outcome::Committed, 12);
let mut second = BenchmarkPass::new("replay-tagged");
second.count(Outcome::Committed, 4);
record.push(first);
record.push(second);
let summary = record.summary();
assert!(!summary.contains('\n'));
assert!(summary.contains("replay-all"));
assert!(summary.contains("replay-tagged"));
assert_eq!(
record.pass("replay-tagged").map(BenchmarkPass::events),
Some(4)
);
assert_eq!(record.pass("nothing"), None);
}
#[test]
fn the_three_refusal_kinds_stay_apart() {
let violated: Result<
happenstance_core::SequencePosition,
happenstance_core::AppendError<core::convert::Infallible>,
> = Err(happenstance_core::AppendError::ExceedsStoreLimit {
limit: happenstance_core::StoreLimit::EventsPerBatch,
len: 9,
});
assert_eq!(Outcome::of_append(&violated), Outcome::Refused);
let empty: Result<
happenstance_core::SequencePosition,
happenstance_core::AppendError<core::convert::Infallible>,
> = Err(happenstance_core::AppendError::NoEvents);
assert_eq!(Outcome::of_append(&empty), Outcome::Failed);
}
#[test]
fn an_incomplete_record_is_well_formed_all_the_same() {
let mut record =
BenchmarkRecord::new("conditional_append_under_contention", &["seed", "contend"]);
let mut seed = BenchmarkPass::new("seed");
seed.count(Outcome::Rejected, 0);
record.push(seed);
assert!(record.is_well_formed());
assert!(!record.is_complete());
assert_eq!(record.missing_passes(), vec!["contend"]);
}
#[test]
#[should_panic(expected = "does not declare")]
fn a_pass_the_scenario_did_not_declare_is_refused() {
let mut record = BenchmarkRecord::new("conditional_append_under_contention", &["seed"]);
let mut contended = BenchmarkPass::new("contend");
contended.count(Outcome::Committed, 1);
record.push(contended);
}
#[test]
#[should_panic(expected = "batch_size")]
fn a_zero_batch_size_is_refused() {
let _ = BenchmarkParams::new(0, 1, 1);
}
}