#moonbench

#Why

#Install

moon add sa2360/moonbench

{
  "import": [
    {
      "path": "sa2360/moonbench",
      "alias": "bench"
    }
  ]
}

let set = @bench.sample_set_from([1_000_000, 1_200_000, 1_100_000])
println(@bench.sample_set_json(set))

#API

• empty() -> Summary
• singleton(elapsed_ns : Int) -> Summary
• sample_set() -> SampleSet
• sample_set_from(samples : Array[Int]) -> SampleSet
• SampleFilter
• filter_samples(set : SampleSet, filter : SampleFilter) -> SampleSet
• trim_samples(set : SampleSet, drop_each_side : Int) -> SampleSet
• drop_warmup(set : SampleSet, warmup_count : Int) -> SampleSet
• clamp_samples(set : SampleSet, min_ns : Int, max_ns : Int) -> SampleSet
• Budget
• Comparison
• Quality
• Clock
• system_clock() -> Clock
• measure(run : () -> Unit) -> Int
• measure_with_clock(clock : Clock, run : () -> Unit) -> Int
• benchmark(iterations : Int, run : () -> Unit) -> Summary
• benchmark_with_clock(iterations : Int, clock : Clock, run : () -> Unit) -> SampleSet
• has_samples(summary : Summary) -> Bool
• Summary::add_sample(summary : Summary, elapsed_ns : Int) -> Summary
• SampleSet::add_sample(set : SampleSet, elapsed_ns : Int) -> SampleSet
• merge(left : Summary, right : Summary) -> Summary
• percentile_ns(set : SampleSet, pct : Int) -> Int
• variance_ns2(set : SampleSet) -> Double
• std_dev_ns(set : SampleSet) -> Double
• distribution(set : SampleSet) -> Distribution
• spread_ns(summary : Summary) -> Int
• relative_spread_ppm(summary : Summary) -> Int
• std_dev_ppm(set : SampleSet) -> Int
• quality(set : SampleSet, tolerance_ppm : Int) -> Quality
• samples_per_second(summary : Summary) -> Int
• is_stable(summary : Summary, tolerance_ppm : Int) -> Bool
• summary_csv_header() -> String
• summary_csv(summary : Summary) -> String
• summary_json(summary : Summary) -> String
• distribution_json(distribution : Distribution) -> String
• sample_set_json(set : SampleSet) -> String
• summary_markdown(summary : Summary) -> String
• sample_set_markdown(set : SampleSet) -> String
• quality_report(set : SampleSet, tolerance_ppm : Int) -> String
• format_ns(ns : Int) -> String
• describe(summary : Summary) -> String
• meets_budget(summary : Summary, budget : Budget) -> Bool
• budget_report(summary : Summary, budget : Budget) -> String
• compare_to_baseline(current : Summary, baseline : Summary) -> Comparison
• within_regression_budget(current : Summary, baseline : Summary, tolerance_ppm : Int) -> Bool
• regression_report(current : Summary, baseline : Summary, tolerance_ppm : Int) -> String

#Example

let summary = @bench.benchmark(5, () => {
  let mut total = 0
  for i in 0..<20_000_000 {
    total = total + i % 17
  }
  ignore(total)
})

println(@bench.describe(summary))
println("spread=\{@bench.format_ns(@bench.spread_ns(summary))}")
println("stable(5%)=\{@bench.is_stable(summary, 50_000)}")

count=5, mean=13 ms, min=11 ms, max=23 ms, throughput=72/s
spread=12 ms
stable(5%)=false

#Reports and Percentiles

let set = @bench.sample_set_from([100, 140, 160, 200])
let dist = @bench.distribution(set)

println(@bench.summary_csv_header())
println(@bench.summary_csv(set.summary))
println(@bench.sample_set_json(set))
println("p95=\{@bench.format_ns(dist.p95_ns)}")

#Imported Samples, Cleanup, and Regression Checks

let imported = @bench.sample_set_from([0, 12_000_000, 12_400_000, 80_000_000])
let cleaned = @bench.filter_samples(
  imported,
  @bench.SampleFilter::{ min_ns: 1, max_ns: 50_000_000, drop_zero: true },
)
let baseline = @bench.sample_set_from([12_200_000, 12_200_000, 12_300_000])

println(@bench.sample_set_markdown(cleaned))
println(@bench.regression_report(cleaned.summary, baseline.summary, 80_000))

#Data-Backed Example

#Platform Clock Adapter

let mut tick = 0
let fake_clock = @bench.Clock::{
  name: "deterministic",
  now_ns: () => {
    tick = tick + 10
    tick
  },
}

let set = @bench.benchmark_with_clock(3, fake_clock, () => ignore(1 + 1))
println(@bench.sample_set_json(set))

#Run

moon check
moon build
moon fmt
moon info
moon test
moon run cmd/main

#OSC2026 Checklist

• Public repository: https://github.com/sa2360/moonbit.
• MoonBit as main language: source is in .mbt files.
• README: this file explains motivation, API, example, and commands.
• Runnable example: cmd/main.
• Tests: moonbench_test.mbt.
• CI: .github/workflows/ci.yml runs moon check, moon build, formatting, moon info, moon test, and the example.
• License: MIT.
• Mooncakes release: run moon login, then moon publish.