Skip to content

Offline, privacy-first grammar checker. Fast, open-source, Rust-powered

feat(bench): add WASM benchmark harness and native allocation profiler (#3153)

Kacper Kuczkowski5f88c0375f7f
diff --git a/harper-core/benches/spellcheck.rs b/harper-core/benches/spellcheck.rs
index a092a07dc..2dbcf2775 100644
--- a/harper-core/benches/spellcheck.rs
+++ b/harper-core/benches/spellcheck.rs
@@ -16,6 +16,11 @@ static MISSPELLED_MIXED: &str = include_str!("./misspelled_words/mixed.md");
static MISSPELLED_LOWERCASE: &str = include_str!("./misspelled_words/lowercase.md");
static MISSPELLED_CAPITALIZED: &str = include_str!("./misspelled_words/capitalized.md");
+// Shared with alloc_profile.rs (../examples/) and the WASM harness
+// (../../harper-wasm/benches/wasm_bench.js) so numbers stay comparable across tools.
+const MAX_EDIT_DISTANCE: u8 = 3;
+const MAX_RESULTS: usize = 200;
+
type WordList = Vec<Vec<char>>;
type WordCase<'a> = (&'static str, &'a [Vec<char>]);
@@ -97,7 +102,7 @@ fn bench_fuzzy_match(group: &mut BenchmarkGroup<'_, WallTime>, name: &str, words
let dict = FstDictionary::curated();
bench_word_list(group, name, words, |word| {
- black_box(dict.fuzzy_match(word, 3, 200)).len()
+ black_box(dict.fuzzy_match(word, MAX_EDIT_DISTANCE, MAX_RESULTS)).len()
});
}
@@ -114,7 +119,13 @@ fn bench_suggest_correct_spelling(
let dict = FstDictionary::curated();
bench_word_list(group, name, words, |word| {
- black_box(suggest_correct_spelling(word, 200, 3, &*dict)).len()
+ black_box(suggest_correct_spelling(
+ word,
+ MAX_RESULTS,
+ MAX_EDIT_DISTANCE,
+ &*dict,
+ ))
+ .len()
});
}
@@ -133,7 +144,7 @@ fn bench_fuzzy_match_merged_dict_single_child(
merged.add_dictionary(dict);
bench_word_list(group, name, words, |word| {
- black_box(merged.fuzzy_match(word, 3, 200)).len()
+ black_box(merged.fuzzy_match(word, MAX_EDIT_DISTANCE, MAX_RESULTS)).len()
});
}
diff --git a/harper-core/examples/alloc_profile.rs b/harper-core/examples/alloc_profile.rs
new file mode 100644
index 000000000..e8bc9a7fd
--- /dev/null
+++ b/harper-core/examples/alloc_profile.rs
@@ -0,0 +1,114 @@
+//! Counts heap allocations made by `fuzzy_match` across the benchmark word lists.
+//! Allocation is relatively more expensive in WASM than on native, so reducing
+//! allocs/word helps spell-check latency on lower-end devices.
+//!
+//! Run with: `cargo run --example alloc_profile -p harper-core --release`
+
+use std::alloc::{GlobalAlloc, Layout, System};
+use std::hint::black_box;
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+use harper_core::spell::{Dictionary, FstDictionary};
+
+struct CountingAllocator {
+ alloc_count: AtomicUsize,
+ dealloc_count: AtomicUsize,
+}
+
+impl CountingAllocator {
+ fn reset(&self) {
+ self.alloc_count.store(0, Ordering::Relaxed);
+ self.dealloc_count.store(0, Ordering::Relaxed);
+ }
+
+ fn alloc_count(&self) -> usize {
+ self.alloc_count.load(Ordering::Relaxed)
+ }
+
+ fn dealloc_count(&self) -> usize {
+ self.dealloc_count.load(Ordering::Relaxed)
+ }
+}
+
+unsafe impl GlobalAlloc for CountingAllocator {
+ unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
+ self.alloc_count.fetch_add(1, Ordering::Relaxed);
+ unsafe { System.alloc(layout) }
+ }
+
+ unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
+ self.dealloc_count.fetch_add(1, Ordering::Relaxed);
+ unsafe { System.dealloc(ptr, layout) }
+ }
+}
+
+#[global_allocator]
+static ALLOC: CountingAllocator = CountingAllocator {
+ alloc_count: AtomicUsize::new(0),
+ dealloc_count: AtomicUsize::new(0),
+};
+
+// Values duplicated across the WASM harness (harper-wasm/benches/wasm_bench.js)
+// and the criterion bench (benches/spellcheck.rs) so numbers stay comparable.
+const MAX_EDIT_DISTANCE: u8 = 3;
+const MAX_RESULTS: usize = 200;
+
+// Shared with the criterion bench (../benches/spellcheck.rs) to keep numbers comparable.
+static MISSPELLED_MIXED: &str = include_str!("../benches/misspelled_words/mixed.md");
+static MISSPELLED_LOWERCASE: &str = include_str!("../benches/misspelled_words/lowercase.md");
+static MISSPELLED_CAPITALIZED: &str = include_str!("../benches/misspelled_words/capitalized.md");
+
+fn load_word_list(source: &str) -> Vec<Vec<char>> {
+ source
+ .lines()
+ .filter(|l| !l.is_empty())
+ .map(|w| w.chars().collect())
+ .collect()
+}
+
+fn profile_word_list(name: &str, words: &[Vec<char>], dict: &FstDictionary) {
+ ALLOC.reset();
+
+ for word in words {
+ black_box(dict.fuzzy_match(black_box(word.as_slice()), MAX_EDIT_DISTANCE, MAX_RESULTS));
+ }
+
+ let allocs = ALLOC.alloc_count();
+ let deallocs = ALLOC.dealloc_count();
+ let net = allocs as i64 - deallocs as i64;
+ let word_count = words.len();
+
+ println!("{name}:");
+ println!(" words: {word_count}");
+ println!(" allocs: {allocs}");
+ println!(" deallocs: {deallocs}");
+ println!(" net: {net:+}");
+ println!(" allocs/word: {:.1}", allocs as f64 / word_count as f64);
+ println!();
+}
+
+fn main() {
+ // Initialize dictionary before resetting counters so startup allocs are excluded.
+ let dict = FstDictionary::curated();
+ // Warm the AUTOMATON_BUILDERS thread_local so its init allocs aren't counted
+ // against the first measured case.
+ let _ = black_box(dict.fuzzy_match(&['w', 'a', 'r', 'm'], MAX_EDIT_DISTANCE, MAX_RESULTS));
+
+ let mixed = load_word_list(MISSPELLED_MIXED);
+ let lowercase = load_word_list(MISSPELLED_LOWERCASE);
+ let capitalized = load_word_list(MISSPELLED_CAPITALIZED);
+
+ let cases = [
+ ("misspelled_mixed", mixed.as_slice()),
+ ("misspelled_lowercase", lowercase.as_slice()),
+ ("misspelled_capitalized", capitalized.as_slice()),
+ ];
+
+ println!("--- fuzzy_match allocation profile ---");
+ println!("max_edit_distance: {MAX_EDIT_DISTANCE}, max_results: {MAX_RESULTS}");
+ println!();
+
+ for (name, words) in cases {
+ profile_word_list(name, words, &*dict);
+ }
+}
diff --git a/harper-wasm/Cargo.toml b/harper-wasm/Cargo.toml
index e2ab26809..938e96c51 100644
--- a/harper-wasm/Cargo.toml
+++ b/harper-wasm/Cargo.toml
@@ -29,3 +29,4 @@ sysinfo = { version = "0.39.5", default-features = false, features = [ "system"
default = ["typst", "thesaurus"]
typst = ["dep:harper-typst"]
thesaurus = ["harper-core/thesaurus"]
+bench = []
diff --git a/harper-wasm/benches/wasm_bench.js b/harper-wasm/benches/wasm_bench.js
new file mode 100644
index 000000000..b868d3033
--- /dev/null
+++ b/harper-wasm/benches/wasm_bench.js
@@ -0,0 +1,89 @@
+// WASM benchmark harness for harper spell-check.
+//
+// Measures time and throughput for fuzzy_match
+// across the same word lists used by the native Criterion benchmarks.
+//
+// Run via `just bench-wasm`.
+
+import { readFileSync } from "node:fs";
+import { performance } from "node:perf_hooks";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Bench output lives in pkg-bench/ (separate from shipping pkg/) so that
+// `just bench-wasm` doesn't clobber pkg/package.json's main/types/files.
+const pkgDir = join(__dirname, "..", "pkg-bench");
+const wordsDir = join(
+ __dirname,
+ "..",
+ "..",
+ "harper-core",
+ "benches",
+ "misspelled_words",
+);
+
+// Node lacks the fetch-based init that --target web expects, so load the
+// wasm bytes manually and pass them to initSync.
+const wasmModule = await import(pathToFileURL(join(pkgDir, "harper_wasm.js")).href);
+const wasmBytes = readFileSync(join(pkgDir, "harper_wasm_bg.wasm"));
+wasmModule.initSync({ module: wasmBytes });
+
+const MAX_EDIT_DISTANCE = 3;
+const MAX_RESULTS = 200;
+// Warmup lets V8 tier wasm up to TurboFan before measurement. min is the most
+// useful single number for microbenches because it's least affected by GC or
+// scheduler jitter; avg is printed alongside so the spread is visible.
+const WARMUP_ITERS = 5;
+const BENCH_ITERS = 50;
+
+function bench(name, fn) {
+ for (let i = 0; i < WARMUP_ITERS; i++) fn();
+
+ const times = [];
+ let result;
+ for (let i = 0; i < BENCH_ITERS; i++) {
+ const start = performance.now();
+ result = fn();
+ times.push(performance.now() - start);
+ }
+
+ const min = Math.min(...times);
+ const avg = times.reduce((a, b) => a + b, 0) / times.length;
+
+ console.log(`${name}:`);
+ console.log(` min: ${min.toFixed(2)} ms`);
+ console.log(` avg: ${avg.toFixed(2)} ms (${BENCH_ITERS} iters)`);
+ console.log(` results: ${result}`);
+ console.log();
+}
+
+// Same word lists as the native benchmarks.
+const cases = [
+ ["mixed", readFileSync(join(wordsDir, "mixed.md"), "utf-8")],
+ ["lowercase", readFileSync(join(wordsDir, "lowercase.md"), "utf-8")],
+ ["capitalized", readFileSync(join(wordsDir, "capitalized.md"), "utf-8")],
+];
+
+console.log("--- wasm fuzzy_match benchmark ---");
+console.log(
+ `max_edit_distance: ${MAX_EDIT_DISTANCE}, max_results: ${MAX_RESULTS}`,
+);
+console.log();
+
+for (const [name, words] of cases) {
+ const wordCount = words
+ .split("\n")
+ .filter((l) => l.length > 0).length;
+
+ // Pre-parse outside the timed region so we measure fuzzy_match, not parse +
+ // JS->WASM string encoding.
+ const prepared = new wasmModule.PreparedWords(words);
+
+ bench(`fuzzy_match/${name} (${wordCount} words)`, () =>
+ prepared.bench_fuzzy_match(MAX_EDIT_DISTANCE, MAX_RESULTS),
+ );
+ // wasm-bindgen needs explicit free() — wasm-pack --target web doesn't
+ // enable FinalizationRegistry auto-cleanup.
+ prepared.free();
+}
diff --git a/harper-wasm/src/bench.rs b/harper-wasm/src/bench.rs
new file mode 100644
index 000000000..d4035d91f
--- /dev/null
+++ b/harper-wasm/src/bench.rs
@@ -0,0 +1,39 @@
+use harper_core::spell::{Dictionary, FstDictionary};
+use std::sync::Arc;
+use wasm_bindgen::prelude::wasm_bindgen;
+
+// Pre-built word list and dictionary handle for the WASM bench harness —
+// keeps parse and dictionary lookup out of the timed region.
+#[wasm_bindgen]
+pub struct PreparedWords {
+ words: Vec<Vec<char>>,
+ dict: Arc<FstDictionary>,
+}
+
+#[wasm_bindgen]
+impl PreparedWords {
+ #[wasm_bindgen(constructor)]
+ pub fn new(words: &str) -> PreparedWords {
+ PreparedWords {
+ words: words
+ .lines()
+ .filter(|l| !l.is_empty())
+ .map(|l| l.chars().collect())
+ .collect(),
+ dict: FstDictionary::curated(),
+ }
+ }
+
+ // Runs fuzzy_match on each word. Returns the total result count so the
+ // optimizer cannot discard the work.
+ pub fn bench_fuzzy_match(&self, max_edit_distance: u8, max_results: usize) -> usize {
+ let mut total = 0usize;
+ for word in &self.words {
+ total += self
+ .dict
+ .fuzzy_match(word, max_edit_distance, max_results)
+ .len();
+ }
+ total
+ }
+}
diff --git a/harper-wasm/src/lib.rs b/harper-wasm/src/lib.rs
index 125fab2f9..fb5e187f3 100644
--- a/harper-wasm/src/lib.rs
+++ b/harper-wasm/src/lib.rs
@@ -1,5 +1,8 @@
#![doc = include_str!("../README.md")]
+#[cfg(feature = "bench")]
+mod bench;
+
use std::collections::HashMap;
use std::convert::Into;
use std::io::Cursor;
diff --git a/justfile b/justfile
index 2a52b59df..ea6d39438 100644
--- a/justfile
+++ b/justfile
@@ -916,6 +916,30 @@ grep-config query:
config.filter(g => g.Group.label.toLowerCase().includes(q) || g.Group.description.toLowerCase().includes(q))
.forEach(g => console.log(`\x1b[1m${g.Group.label}\x1b[0m: \x1b[36m${g.Group.description}\x1b[0m`));
+# Run the native allocation profiler for spell-check operations.
+alias alloc-prof := alloc-profile
+alloc-profile:
+ cargo run --example alloc_profile -p harper-core --release
+
+# Run native benchmarks.
+bench:
+ cargo bench
+
+# Build harper-wasm with bench support and run the WASM benchmark harness.
+# Runs wasm-opt by default to match the shipping build; set DISABLE_WASM_OPT=1
+# to skip it (faster rebuilds, non-shipping numbers).
+bench-wasm:
+ #!/usr/bin/env bash
+ set -eo pipefail
+
+ cd "{{justfile_directory()}}/harper-wasm"
+ if [ "${DISABLE_WASM_OPT:-0}" -eq 1 ]; then
+ wasm-pack build --target web --no-opt --out-dir pkg-bench --features bench
+ else
+ wasm-pack build --target web --out-dir pkg-bench --features bench
+ fi
+ node benches/wasm_bench.js
+
# search configuration group settings for substring in name
grep-config-settings query:
#! /usr/bin/env node