Skip to content

Get rid of double range copy for aggregation operations over ranges - #352

Merged
h-a-n-a-s-h-i merged 2 commits into
storytold:mainfrom
Fly-Style:fix/memory-alloc-on-agg
Oct 11, 2026
Merged

h-a-n-a-s-h-i merged 2 commits into
storytold:mainfrom
Fly-Style:fix/memory-alloc-on-agg

Conversation

@Fly-Style

Copy link
Copy Markdown
Contributor

Summary

Aggregations such as SUM, COUNT and AVERAGE now add up a range cell by cell instead of first copying the whole range into an array. This removes the 16M-cell limit for them and saves about 24 to 39 bytes of peak memory per range cell. The benchmark behind the numbers below is kept in this description, not in the changeset.

Problem

On a dense 5000 x 5000 sheet (25M cells), =SUM(A1:GJH5000) returned #NUM!, while the status bar showed Sum, Count and Average for the same selection.

A formula's range is copied into an in-memory array before the function sees it. That copy is refused above MAX_CELLS (16M cells, crates/calc/src/eval.rs:15). SUM then copies the numbers a second time in numbers(). The status bar skips both copies because it reads the stored cells in place.

The cap bites only when the sheet's used range itself is above 16M cells: area_value first trims large ranges to the used range, so sparse sheets were not affected.

What changed

Evaluator, crates/calc/src/eval.rs

  • Host gets a default method visit_range() that returns false, so other hosts behave as before.
  • builtin hands SUM, COUNT and AVERAGE to the new Evaluator::aggregate.
  • A small accumulator does the work: Agg names the function and Acc carries a sum and a count. Adding another aggregate means a new Agg variant and, if needed, another field in Acc.
  • A multi-cell block is folded through visit_range. Single cells, blocks the host declines, and non-reference arguments are added by calling the real SUM and COUNT on them (AVERAGE of an argument is its SUM over its COUNT), so coercion and error rules stay in one place.
  • Inside a range, SUM and AVERAGE stop at the first error. COUNT skips errors, as the real functions do.
  • Evaluation order. Arguments are evaluated and read one at a time, in order, exactly like the array path, and the arguments after an error are still evaluated. This matters for volatile formulas: with B2 = RAND()*10, =SUM(B1:B2, RAND()) must read B2 before it draws the second random number. An earlier version of this change evaluated every argument first and got the draws the other way round.

Calculation, crates/calc/src/recalc.rs

  • PassHost::visit_range walks the stored cells of a block in two passes and holds no per-cell data of its own (memory stays constant however many cells the block has):
    1. It reads every formula cell in the block, in row-major order as range_values does. Reading a cell calculates it and the pass remembers the value; this one only discards the result.
    2. It checks for spills. If this pass or the stored sheet has spilled values that touch the block, it declines and the caller falls back to the array path (range_values). The check comes after pass 1 because evaluating a formula in the block can itself produce a spill over the block.
    3. It walks the cells once more, handing each value to the caller. Formula cells are read again, which is now a lookup of the remembered value.

Results

Release build, 3000 x 3000 sheet of repeating digits 0..9 (9M cells), measured with the benchmark in the spoiler below. The array-path numbers come from HEAD (before this change).

Peak heap (heaptrack 1.5.0, one benchmark case per run, HEAD against the final code):

Function ranges copied into an array folded in place saved
SUM 1.14 GB 794 MB 346 MB
COUNT 1.01 GB 794 MB 216 MB
AVERAGE 1.14 GB 794 MB 346 MB
  • The array path's extra memory is vec![Value::Empty; h * w] in range_values (216 MB in one call), plus, for SUM and AVERAGE, the Vec<f64> that numbers() grows with push (134 MB at its peak). COUNT doesn't build that second vector, which is why it saves less.
  • Folding in place adds about 125 KB at its peak.
  • All of the in-place peak is the cell store itself (the BTreeMap holding 9M cells, roughly 84 bytes per cell). That part is the same in both and is outside this change.
  • The saving is about 24 to 39 bytes per range cell, so it scales with range size.

Benchmark used for the numbers (not part of this changeset)

crates/engine/benches/sum.rs (Divan) and how it was run

Add to crates/engine/Cargo.toml:

[dev-dependencies]
divan = "0.1.21"

[[bench]]
name = "sum"
harness = false

crates/engine/benches/sum.rs:

//! Select-all statistics and `=SUM`, `=COUNT` and `=AVERAGE` over a square sheet of repeating digits 0..=9
//! (`(row * n + col) % 10`, n a multiple of 10): sum n*n/10*45, count n*n, average 4.5.
//! `cargo bench -p gridcraft-engine --bench sum` (add a name to filter, e.g. `sum_formula`).

use std::sync::Arc;

use divan::{Bencher, black_box};
use gridcraft_engine::Session;
use gridcraft_engine::core::{CellRef, RangeRef, Value};
use gridcraft_engine::display::stats;
use serde_json::json;

fn main() {
    divan::main();
}

fn col_name(mut c: u32) -> String {
    let mut s = Vec::new();
    loop {
        s.push(b'A' + (c % 26) as u8);
        if c < 26 {
            break;
        }
        c = c / 26 - 1;
    }
    s.reverse();
    String::from_utf8_lossy(&s).into_owned()
}

/// A session whose active sheet holds the n x n digits. Built outside the timed closure.
fn session(n: u32) -> Session {
    let mut s = Session::new();
    s.new_workbook();
    let d = s.active_mut().expect("document");
    let sh = Arc::make_mut(&mut d.wb).sheet_mut(0).expect("sheet");
    for r in 0..n {
        for c in 0..n {
            sh.set_value(CellRef::new(r, c), Value::Number(((u64::from(r) * u64::from(n) + u64::from(c)) % 10) as f64));
        }
    }
    s
}

fn expected_sum(n: u32) -> f64 {
    (u64::from(n) * u64::from(n) / 10 * 45) as f64
}

#[divan::bench(args = [3000, 5000], sample_count = 5, sample_size = 1)]
fn stats_select_all(bencher: Bencher, n: u32) {
    let s = session(n);
    let sheet = s.active().expect("document").wb.active().expect("sheet");
    let all = RangeRef::new(CellRef::new(0, 0), CellRef::new(n - 1, n - 1));
    let st = stats(sheet, &[all]);
    assert_eq!((st.sum, st.average), (expected_sum(n), Some(4.5)));
    bencher.bench(|| stats(black_box(sheet), black_box(&[all])));
}

/// Enters `=FUNC(whole block)` beside the data; checks the value, then times re-entering it.
fn bench_formula(bencher: Bencher, func: &str, n: u32, want: f64) {
    let mut s = session(n);
    let (at, input) = (format!("{}1", col_name(n + 1)), format!("={func}(A1:{}{n})", col_name(n - 1)));
    let enter = |s: &mut Session| s.execute("cell.set", json!({"cell": at, "input": input})).expect("cell.set");
    enter(&mut s);
    let got = s.active().expect("document").wb.active().expect("sheet").value(CellRef::new(0, n + 1));
    assert_eq!(got, Value::Number(want));
    bencher.bench_local(|| black_box(enter(&mut s)));
}

#[divan::bench(args = [3000, 5000], sample_count = 5, sample_size = 1)]
fn sum_formula(bencher: Bencher, n: u32) {
    bench_formula(bencher, "SUM", n, expected_sum(n));
}

#[divan::bench(args = [3000, 5000], sample_count = 5, sample_size = 1)]
fn count_formula(bencher: Bencher, n: u32) {
    bench_formula(bencher, "COUNT", n, f64::from(n) * f64::from(n));
}

#[divan::bench(args = [3000, 5000], sample_count = 5, sample_size = 1)]
fn average_formula(bencher: Bencher, n: u32) {
    bench_formula(bencher, "AVERAGE", n, 4.5);
}

Timings: cargo bench -p gridcraft-engine --bench sum (add a name to filter).

Peak heap, one case per run, once on the final code and once on an unmodified HEAD in a separate git worktree (with sum.rs, the Cargo.toml lines and Cargo.lock copied in):

CARGO_PROFILE_BENCH_DEBUG=true cargo bench -p gridcraft-engine --bench sum --no-run   # prints the binary path
heaptrack -o /tmp/ht <binary> "sum_formula::3000"        # also count_formula::3000, average_formula::3000
heaptrack_print -f /tmp/ht.zst -n 1 | grep "peak heap"

Not changed

  • The status-bar statistics (display::stats) don't use the evaluator.

Please look at

  1. PassHost::visit_range. It relies on iter_range being row-major, so the first error and the order of float additions match the array path.
  2. Rounding. With several arguments, each non-range argument is added as its own chunk. The last digits can differ from the array path when an array-valued argument is not the only argument. A single range gives identical results.
  3. The extra pass. The formula-reading pass plus the walk make the in-place path about 30% slower than the array path where both work. Skipping the first pass for blocks with no formulas would remove most of the gap. Not done here.

Try it

Generate and ppen a sheet with more than 16M used cells and enter, e.g., =SUM(B2:GZA5500) in A1. Before this change it shows #NUM!; now it shows the sum.

h-a-n-a-s-h-i pushed a commit that referenced this pull request Oct 11, 2026
Get rid of double range copy for aggregation operations over ranges

# Conflicts:
#	crates/calc/src/tests.rs
@h-a-n-a-s-h-i
h-a-n-a-s-h-i merged commit a4fc107 into storytold:main Oct 11, 2026
@echelon

echelon commented Oct 11, 2026

Copy link
Copy Markdown
Member

Merged — thank you for the contribution!

If you haven't already, come join us on the ArtCraft Discord: https://discord.gg/artcraft

@Fly-Style
Fly-Style deleted the fix/memory-alloc-on-agg branch October 11, 2026 16:41
@Fly-Style

Copy link
Copy Markdown
Contributor Author

@echelon thanks for quick merge!
Already in Discord, submitted a PR and then submitted a review request: https://discord.com/channels/1359579021108842617/1557515969092657183/1558856273750134784

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants