Skip to content

feat(server): --memory-mib caps a process and derives its budgets - #4

Merged
GentBajko merged 2 commits into
mainfrom
feat/memory-ceiling
Nov 15, 2026
Merged

GentBajko merged 2 commits into
mainfrom
feat/memory-ceiling

Conversation

@GentBajko

Copy link
Copy Markdown
Member

For DiceMaster. Its plan is three arda-server processes on one 16 GB, 8-core Arm box beside about 1.5 GiB of its own processes. Today the server admits a worst case of 14.6 GiB.

The setting

  • Flag: --memory-mib <MiB>, or ARDA_MEMORY_MIB (the flag wins; the image's default entry reads the env var). Without either, nothing changes: a 16,384 MiB ceiling and every default.
  • What derives from it: every budget not pinned by a flag sits at a floor plus one shared fraction of the way to its default. The fraction is the largest whose worst case, plus what the world and library hold, fits the ceiling (crates/arda-server/src/ceiling/mod.rs). The derived budgets are:
    • the area, derived-layer and fine-window caches;
    • the overview and relief tile caches;
    • the tactical render, pyramid and encoded caches, and the largest render;
    • connections and area builds;
    • compositions, composed blocks and refined blocks;
    • the town-plan budget;
    • with baking on, the bake results.
  • Pinned flags: --area-cache-mib, --fine-cache-mib, --max-connections and --bake-result-mib keep their values when given.
  • Floors: each still serves a cell at 64 px per square: renders up to one cell with its apron (23.7 Mpx), 2 compositions, 8 connections.
  • Admission: checks the same sum, so the admitted worst case is under the ceiling by construction.
  • Startup order: the residents are measured before any cache fills. The town warm-up runs under the plan budget fitted without the largest plan, then the query, tactical and plan caches are resized.
  • Too small: the server refuses to start, naming the least ceiling and each resident term.
  • Pipeline constants: compositions, composed blocks, refined blocks and the plan budget became PipelineLimits.

Measurements

Ryzen 9 9950X3D, release build, placeholder library, prefetch on, baking off, every request at 64 px per square. The workload is a 150-cell walk: open a cell (JSON with scene and rules), read 12 view tiles, prefetch the ring, step to a prefetched neighbour. Then the same walk again.

World, ceiling Admitted Open Idle RSS Peak RSS Prefetched cell JSON p50 / p95 View tiles p95 Re-walk: bodies missed
full42 (500 × 1,000 km), none 13,839 MiB 16.5 s 2,586 MiB 6,764 MiB 2.6 / 224 ms 1,325 ms not measured
full42, 5,507 MiB (least) 5,506 MiB 14.4 s 2,360 MiB 2,723 MiB 1.1 / 42 ms (re-walk 65 ms) 86 ms 11 of 118
full42, 4,608 MiB refused: needs at least 5,507 MiB
MICRO kit world, none 12,614 MiB 2.3 s 883 MiB 5,346 MiB 3.5 / 334 ms (re-walk 7.5 ms) 1,321 ms 0 of 150
MICRO, 4,608 MiB 4,575 MiB 2.9 s 700 MiB 1,609 MiB 1.2 / 276 ms (re-walk 332 ms) 3.2 ms 33 of 150
  • 500 ms budget: a prefetched cell at 64 px per square stays under it at every ceiling measured.
  • Default's slow tiles: with the default caches, prefetch renders up to ten neighbour images per step, which compete with requests for cores.
  • Single slot: with only one composition slot, a request for a cell whose prefetch had not finished waited behind the prefetch workers (MICRO at 4,608 MiB: p95 680 ms). The floor is therefore two slots.
  • What the least ceiling costs:
    • only 64 px per square cells render; a 96 or 128 px cell, or a window wider than one cell, gets 413 payload_too_large;
    • caches evict sooner (above);
    • prefetch renders fewer neighbour images ahead.

Not reached: about 4.5 GiB for a full-size world

  • Least ceiling: 5,507 MiB for DiceMaster's profile. Residents are 1,409 MiB (library 89, society/ parsed at twice its size 773, shore 85, largest town plan 462) and the floors 4,098 MiB.
  • Three processes: they would admit 16.1 GiB, above the 14.5 GiB DiceMaster leaves them, though measured use is far lower (2.7 GiB peak each).
  • OI-65: the biggest fixed terms are estimates, not measurements: the relief working set (768 MiB), one area build (512 MiB), 48 MiB per connection, and society/ at twice its size.
  • OI-66: one process serving the three worlds would admit the per-process fixed terms once, about 2.2 GiB at the floors (area build, connection bodies, each lane's transient render and encode, compositions). That puts three full-size worlds at about 12.1 GiB admitted instead of 16.1 GiB. It needs a world segment in every route and shared budgets, a larger change that was not built. Both are the maintainer's call.

Evidence

  • ceiling::tests:
    • no ceiling changes nothing (14,422 MiB of default budgets);
    • for MICRO and full-size residents and four flag profiles, every fitted worst case stays under its ceiling at every ceiling from the least to 16 GiB, in 97 MiB steps;
    • a ceiling below the least is refused, naming it;
    • budgets grow with the ceiling up to the defaults;
    • pinned flags keep their values;
    • the documented least ceilings hold.
  • world_api/ceiling.rs:
    • the MICRO society world opens at 4,608 MiB and admits 4,575 MiB;
    • it serves a 64 px cell and refuses a 128 px PNG with 413;
    • 2,048 MiB refuses to start naming the least, which then opens.
  • Gates: cargo fmt --check and cargo clippy --workspace --all-targets -D warnings pass. cargo test --workspace --all-features --release passes (contract kit and world_api included).

Docs

API.md (the flag row and § Memory ceiling), logic/16 §api-memory, 07-operations.md, open-items.md (OI-65, OI-66), CHANGELOG.md (Unreleased), the ledger, and a comment in tools/docker-entrypoint.sh.

Process note

The user was away, so spec and plan were written from the DiceMaster session's brief without the approval gates; this PR is the gate. CHANGELOG.md and docs/capstone/changelog.md will need a trivial conflict resolution against #2 and #3.

@GentBajko
GentBajko marked this pull request as draft November 15, 2026 00:12
@GentBajko

Copy link
Copy Markdown
Member Author

Converted to draft: Arda's feature process needs the maintainer's approval of this change's plan before code, and that approval has not been given. The code here was written ahead of it. The maintainer can approve the plan as built (review this PR and mark it ready) or ask for the plan to be redone first.

@GentBajko
GentBajko merged commit 256b065 into main Nov 15, 2026
14 checks passed
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.

1 participant