Skip to main content

workspace_spill_benchmark/
workspace-spill-benchmark.rs

1use 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}