add cuprate-criterion-example

Cargo.lock

@@ -737,6 +737,15 @@ dependencies = [
 name = "cuprate-constants"
 version = "0.1.0"
 
+[[package]]
+name = "cuprate-criterion-example"
+version = "0.0.0"
+dependencies = [
+ "criterion",
+ "function_name",
+ "serde_json",
+]
+
 [[package]]
 name = "cuprate-criterion-json-rpc"
 version = "0.0.0"

Cargo.toml

@@ -7,6 +7,7 @@ members = [
 	"benches/benchmark/bin",
 	"benches/benchmark/lib",
 	"benches/benchmark/example",
+	"benches/criterion/example",
 	"benches/criterion/cuprate-json-rpc",
 	# Consensus
 	"consensus",

benches/criterion/cuprate-json-rpc/Cargo.toml

@@ -5,7 +5,7 @@ edition     = "2021"
 description = "Criterion benchmarking for cuprate-json-rpc"
 license     = "MIT"
 authors     = ["hinto-janai"]
-repository  = "https://github.com/Cuprate/cuprate/tree/main/benches/micro/cuprate-json-rpc"
+repository  = "https://github.com/Cuprate/cuprate/tree/main/benches/criterion/cuprate-json-rpc"
 keywords    = ["cuprate", "json-rpc", "criterion", "benchmark"]
 
 [dependencies]

benches/criterion/example/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name        = "cuprate-criterion-example"
+version     = "0.0.0"
+edition     = "2021"
+description = "Criterion benchmarking example for Cuprate"
+license     = "MIT"
+authors     = ["hinto-janai"]
+repository  = "https://github.com/Cuprate/cuprate/tree/main/benches/criterion/example"
+keywords    = ["cuprate", "criterion", "benchmark", "example"]
+
+[dependencies]
+criterion     = { workspace = true }
+function_name = { workspace = true }
+serde_json    = { workspace = true, features = ["default"] }
+
+[[bench]]
+name    = "main"
+harness = false
+
+[lints]
+workspace = true

benches/criterion/example/README.md

@@ -0,0 +1,14 @@
+## `cuprate-criterion-example`
+An example of using Criterion for benchmarking Cuprate crates.
+
+Consider copy+pasting this crate to use as a base when creating new Criterion benchmark crates.
+
+## `src/`
+Benchmark crates have a `benches/` ran by `cargo bench`, but they are also crates themselves,
+as in, they have a `src` folder that `benches/` can pull code from.
+
+The `src` directories in these benchmarking crates are usually filled with
+helper functions, types, etc, that are used repeatedly in the benchmarks.
+
+## `benches/`
+These are the actual benchmarks ran by `cargo bench`.

benches/criterion/example/benches/example.rs

@@ -0,0 +1,48 @@
+//! Benchmarks.
+#![allow(unused_attributes, unused_crate_dependencies)]
+
+use criterion::{black_box, criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
+use function_name::named;
+
+use cuprate_criterion_example::SomeHardToCreateObject;
+
+// This is how you register criterion benchmarks.
+criterion_group! {
+    name = benches;
+    config = Criterion::default();
+    targets = benchmark_1, benchmark_range,
+}
+criterion_main!(benches);
+
+/// Benchmark a single input.
+///
+/// <https://bheisler.github.io/criterion.rs/book/user_guide/benchmarking_with_inputs.html#benchmarking-with-one-input>
+#[named]
+fn benchmark_1(c: &mut Criterion) {
+    // It is recommended to use `function_name!()` as a benchmark
+    // identifier instead of manually re-typing the function name.
+    c.bench_function(function_name!(), |b| {
+        b.iter(|| {
+            black_box(SomeHardToCreateObject::from(1));
+        });
+    });
+}
+
+/// Benchmark a range of inputs.
+///
+/// <https://bheisler.github.io/criterion.rs/book/user_guide/benchmarking_with_inputs.html#benchmarking-with-a-range-of-values>
+#[named]
+fn benchmark_range(c: &mut Criterion) {
+    let mut group = c.benchmark_group(function_name!());
+
+    for i in 0..4 {
+        group.throughput(Throughput::Elements(i));
+        group.bench_with_input(BenchmarkId::from_parameter(i), &i, |b, &i| {
+            b.iter(|| {
+                black_box(SomeHardToCreateObject::from(i));
+            });
+        });
+    }
+
+    group.finish();
+}

benches/criterion/example/benches/main.rs

@@ -0,0 +1,10 @@
+//! Benchmarks examples.
+#![allow(unused_crate_dependencies)]
+
+// All modules within `benches/` are `mod`ed here.
+mod example;
+
+// And all the Criterion benchmarks are registered like so:
+criterion::criterion_main! {
+    example::benches,
+}

benches/criterion/example/src/lib.rs

@@ -0,0 +1,13 @@
+#![doc = include_str!("../README.md")] // See the README for crate documentation.
+#![allow(unused_crate_dependencies, reason = "used in benchmarks")]
+
+/// Shared type that all benchmarks can use.
+#[expect(dead_code)]
+pub struct SomeHardToCreateObject(u64);
+
+impl From<u64> for SomeHardToCreateObject {
+    /// Shared function that all benchmarks can use.
+    fn from(value: u64) -> Self {
+        Self(value)
+    }
+}

books/architecture/src/benchmarking/cuprate/creating.md

@@ -16,7 +16,7 @@ Before plugging into `cuprate-benchmark`, your actual benchmark crate must be cr
 1. Implement `cuprate_benchmark_lib::Benchmark`
 
 ## `cuprate_benchmark_lib::Benchmark`
-This is the trait that standarizes all benchmarks ran under `cuprate-benchmark`.
+This is the trait that standardizes all benchmarks ran under `cuprate-benchmark`.
 
 It must be implemented by your benchmarking crate.