workspace_spill_benchmark/
workspace-spill-benchmark.rs1use std::collections::BTreeMap;
2use std::path::{Path, PathBuf};
3use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
4use std::sync::Arc;
5use std::time::{Duration, Instant};
6
7use littlegraph_core::{Graph, Neo4jStorage, TransactionOptions, Value};
8
9#[derive(Debug)]
10struct Options {
11 fixture: Option<PathBuf>,
12 update_existing: bool,
13 nodes: usize,
14 payload_bytes: usize,
15 spill_threshold_bytes: Option<usize>,
16 max_spill_bytes: u64,
17 max_journal_bytes: Option<u64>,
18 sample_interval: Duration,
19}
20
21impl Default for Options {
22 fn default() -> Self {
23 Self {
24 fixture: None,
25 update_existing: false,
26 nodes: 40,
27 payload_bytes: 24,
28 spill_threshold_bytes: None,
29 max_spill_bytes: 256 * 1024 * 1024,
30 max_journal_bytes: None,
31 sample_interval: Duration::from_millis(2),
32 }
33 }
34}
35
36fn main() -> Result<(), Box<dyn std::error::Error>> {
37 let options = parse_options()?;
38 let directory = tempfile::tempdir()?;
39 let database = prepare_database(directory.path(), options.fixture.as_deref())?;
40 let mut graph = Graph::open_neo4j_writable(&database)?;
41
42 let baseline_rss_kib = resident_set_kib().unwrap_or(0);
43 let stop = Arc::new(AtomicBool::new(false));
44 let peak_rss_kib = Arc::new(AtomicU64::new(baseline_rss_kib));
45 let peak_spill_bytes = Arc::new(AtomicU64::new(0));
46 let sampler = spawn_sampler(
47 database.clone(),
48 options.sample_interval,
49 stop.clone(),
50 peak_rss_kib.clone(),
51 peak_spill_bytes.clone(),
52 );
53
54 let total_start = Instant::now();
55 let mut transaction = graph.transaction_with_options(TransactionOptions {
56 spill_threshold_bytes: options.spill_threshold_bytes,
57 max_spill_bytes: Some(options.max_spill_bytes),
58 max_journal_bytes: options.max_journal_bytes,
59 ..TransactionOptions::default()
60 })?;
61 let payload = if options.update_existing { "y" } else { "x" }.repeat(options.payload_bytes);
62 let mutation_start = Instant::now();
63 for ordinal in 0..options.nodes {
64 let params = BTreeMap::from([
65 (
66 "ordinal".to_owned(),
67 Value::Integer(i64::try_from(ordinal)?),
68 ),
69 ("payload".to_owned(), Value::String(payload.clone())),
70 ]);
71 let result = if options.update_existing {
72 transaction.query(
73 "MATCH (n:LittlegraphSpillCapacity {ordinal: $ordinal}) SET n.payload = $payload RETURN n.ordinal",
74 params,
75 )?
76 } else {
77 transaction.query(
78 "CREATE (:SpillBenchmark {ordinal: $ordinal, payload: $payload})",
79 params,
80 )?
81 };
82 if options.update_existing && result.rows.len() != 1 {
83 return Err(format!(
84 "expected one LittlegraphSpillCapacity node for ordinal {ordinal}, found {}",
85 result.rows.len()
86 )
87 .into());
88 }
89 }
90 let mutation_elapsed = mutation_start.elapsed();
91 let commit_start = Instant::now();
92 transaction.commit()?;
93 let commit_elapsed = commit_start.elapsed();
94 let total_elapsed = total_start.elapsed();
95
96 sample_peaks(&database, &peak_rss_kib, &peak_spill_bytes);
97 stop.store(true, Ordering::Release);
98 sampler.join().map_err(|_| "workspace sampler panicked")?;
99
100 let peak_rss_kib = peak_rss_kib.load(Ordering::Relaxed);
101 println!(
102 "{{\"fixture\":{},\"update_existing\":{},\"nodes\":{},\"payload_bytes\":{},\"spill_threshold_bytes\":{},\"max_spill_bytes\":{},\"max_journal_bytes\":{},\"sample_interval_us\":{},\"baseline_rss_kib\":{},\"peak_rss_kib\":{},\"rss_delta_kib\":{},\"peak_spill_bytes\":{},\"mutation_ms\":{:.3},\"commit_ms\":{:.3},\"total_ms\":{:.3}}}",
103 options.fixture.is_some(),
104 options.update_existing,
105 options.nodes,
106 options.payload_bytes,
107 options
108 .spill_threshold_bytes
109 .map_or_else(|| "null".to_owned(), |value| value.to_string()),
110 options.max_spill_bytes,
111 options
112 .max_journal_bytes
113 .map_or_else(|| "null".to_owned(), |value| value.to_string()),
114 options.sample_interval.as_micros(),
115 baseline_rss_kib,
116 peak_rss_kib,
117 peak_rss_kib.saturating_sub(baseline_rss_kib),
118 peak_spill_bytes.load(Ordering::Relaxed),
119 mutation_elapsed.as_secs_f64() * 1000.0,
120 commit_elapsed.as_secs_f64() * 1000.0,
121 total_elapsed.as_secs_f64() * 1000.0,
122 );
123 Ok(())
124}
125
126fn parse_options() -> Result<Options, Box<dyn std::error::Error>> {
127 let mut options = Options::default();
128 let mut arguments = std::env::args().skip(1);
129 while let Some(argument) = arguments.next() {
130 if argument == "--update-existing" {
131 options.update_existing = true;
132 continue;
133 }
134 let value = match argument.as_str() {
135 "--help" | "-h" => {
136 print_help();
137 std::process::exit(0);
138 }
139 "--fixture"
140 | "--nodes"
141 | "--payload-bytes"
142 | "--spill-threshold-bytes"
143 | "--max-spill-bytes"
144 | "--max-journal-bytes"
145 | "--sample-interval-us" => arguments
146 .next()
147 .ok_or_else(|| format!("{argument} requires a value"))?,
148 _ => return Err(format!("unknown argument: {argument}").into()),
149 };
150 match argument.as_str() {
151 "--fixture" => options.fixture = Some(PathBuf::from(value)),
152 "--nodes" => options.nodes = value.parse()?,
153 "--payload-bytes" => options.payload_bytes = value.parse()?,
154 "--spill-threshold-bytes" => {
155 options.spill_threshold_bytes = if value == "none" {
156 None
157 } else {
158 Some(value.parse()?)
159 }
160 }
161 "--max-spill-bytes" => options.max_spill_bytes = value.parse()?,
162 "--max-journal-bytes" => {
163 options.max_journal_bytes = if value == "none" {
164 None
165 } else {
166 Some(value.parse()?)
167 }
168 }
169 "--sample-interval-us" => {
170 options.sample_interval = Duration::from_micros(value.parse()?);
171 }
172 _ => unreachable!(),
173 }
174 }
175 if options.nodes == 0 || options.payload_bytes == 0 || options.sample_interval.is_zero() {
176 return Err("nodes, payload bytes, and sample interval must be positive".into());
177 }
178 if options.fixture.is_none() && options.payload_bytes > 27 {
179 return Err(
180 "payloads above 27 bytes require --fixture with dynamic-record capacity".into(),
181 );
182 }
183 if options.update_existing && options.fixture.is_none() {
184 return Err("--update-existing requires --fixture".into());
185 }
186 Ok(options)
187}
188
189fn print_help() {
190 println!(
191 "workspace-spill-benchmark\n\n\
192 Options:\n\
193 --fixture PATH Normally closed Neo4j database copied before the run\n\
194 --update-existing Update LittlegraphSpillCapacity fixture nodes\n\
195 --nodes N Nodes created in one transaction (default: 40)\n\
196 --payload-bytes N String property bytes per node (default: 24)\n\
197 --spill-threshold-bytes N Resident record threshold; use 'none' to disable\n\
198 --max-spill-bytes N Physical spill-file cap (default: 268435456)\n\
199 --max-journal-bytes N Encoded commit-journal cap; use 'none' for 1 GiB\n\
200 --sample-interval-us N RSS/file sampling interval (default: 2000)"
201 );
202}
203
204fn prepare_database(
205 benchmark_home: &Path,
206 fixture: Option<&Path>,
207) -> Result<PathBuf, Box<dyn std::error::Error>> {
208 let database_name = fixture
209 .and_then(Path::file_name)
210 .unwrap_or_else(|| std::ffi::OsStr::new("neo4j"));
211 let database = benchmark_home.join("data/databases").join(database_name);
212 let Some(fixture) = fixture else {
213 Neo4jStorage::initialize_if_empty(&database)?;
214 return Ok(database);
215 };
216
217 copy_directory(fixture, &database)?;
218 let data_directory = fixture
219 .parent()
220 .and_then(Path::parent)
221 .ok_or("fixture must have the form <home>/data/databases/<name>")?;
222 let source_transactions = data_directory.join("transactions").join(database_name);
223 if source_transactions.is_dir() {
224 copy_directory(
225 &source_transactions,
226 &benchmark_home.join("data/transactions").join(database_name),
227 )?;
228 }
229 Ok(database)
230}
231
232fn copy_directory(source: &Path, target: &Path) -> Result<(), Box<dyn std::error::Error>> {
233 std::fs::create_dir_all(target)?;
234 for entry in std::fs::read_dir(source)? {
235 let entry = entry?;
236 let file_type = entry.file_type()?;
237 let target_path = target.join(entry.file_name());
238 if file_type.is_dir() {
239 copy_directory(&entry.path(), &target_path)?;
240 } else if file_type.is_file() {
241 std::fs::copy(entry.path(), target_path)?;
242 } else {
243 return Err(format!(
244 "fixture contains an unsupported non-regular entry: {}",
245 entry.path().display()
246 )
247 .into());
248 }
249 }
250 Ok(())
251}
252
253fn spawn_sampler(
254 database: std::path::PathBuf,
255 interval: Duration,
256 stop: Arc<AtomicBool>,
257 peak_rss_kib: Arc<AtomicU64>,
258 peak_spill_bytes: Arc<AtomicU64>,
259) -> std::thread::JoinHandle<()> {
260 std::thread::spawn(move || {
261 while !stop.load(Ordering::Acquire) {
262 sample_peaks(&database, &peak_rss_kib, &peak_spill_bytes);
263 std::thread::sleep(interval);
264 }
265 sample_peaks(&database, &peak_rss_kib, &peak_spill_bytes);
266 })
267}
268
269fn sample_peaks(database: &Path, peak_rss_kib: &AtomicU64, peak_spill_bytes: &AtomicU64) {
270 if let Some(rss_kib) = resident_set_kib() {
271 peak_rss_kib.fetch_max(rss_kib, Ordering::Relaxed);
272 }
273 peak_spill_bytes.fetch_max(spill_bytes(database), Ordering::Relaxed);
274}
275
276fn resident_set_kib() -> Option<u64> {
277 let status = std::fs::read_to_string("/proc/self/status").ok()?;
278 let line = status.lines().find(|line| line.starts_with("VmRSS:"))?;
279 line.split_whitespace().nth(1)?.parse().ok()
280}
281
282fn spill_bytes(database: &Path) -> u64 {
283 let directory = database.join(".littlegraph-transactions");
284 let Ok(entries) = std::fs::read_dir(directory) else {
285 return 0;
286 };
287 entries
288 .filter_map(|entry| entry.ok())
289 .filter_map(|entry| entry.metadata().ok())
290 .filter(|metadata| metadata.is_file())
291 .map(|metadata| metadata.len())
292 .sum()
293}