This repository was archived by the owner on Nov 21, 2026. It is now read-only.
Repository navigation
JVM: opt-in JDK 25 AOT cache (ARCADEDB_AOT=1) with fault and concurrency probes - #490
Merged
Merged
Conversation
Per-user cache of the classes the JVM loads and links at start, keyed by package version, bundled JRE, jars and class path. One process trains at a time (lock file, unique temp file), the next start validates it with the bundled JVM and renames it into place; a cache whose size or sha256 differs is rebuilt. Every failure is a normal start. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… training lock and re-raise Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The only subprocess runs the wheel's own java with an argv list, fixed flags and our cache path; no shell, no user input. CI's Bandit command (bandit 1.9.4, -c pyproject.toml, low/low) reports no issues. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
undo() restored the real sys.platform, so on macOS and Windows cache_dir() left XDG_CACHE_HOME for ~/Library/Caches or %LOCALAPPDATA% and the damaged-cache test looked at a directory the plan never used (5 failures per job). Reproduced on Linux by forcing sys.platform=darwin: 5 failed before, 27 passed after. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tae898
force-pushed
the
jvm/aot-cache-opt-in
branch
from
October 24, 2026 01:29
5de6e08 to
3cbf5e0
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
An opt-in Project Leyden AOT cache (JDK 25, JEP 483/514/515) for the JVM wheel.
ARCADEDB_AOT=1orstart_jvm(aot=True)(alsojvm_kwargs={"aot": True}) lets the JVM keep a per-user cache of the classes it loads and links at start. It is off by default, and nothing changes for anyone who does not set it. New modulearcadedb_embedded/aot.py, a small hook instart_jvm, tests intests/test_aot.py, a section indocs/api/jvm.mdand a line indocs/development/architecture.md.$XDG_CACHE_HOME/arcadedb/aotor~/.cache/arcadedb/aot(macOS~/Library/Caches/arcadedb/aot, Windows%LOCALAPPDATA%\arcadedb\Cache\aot);ARCADEDB_AOT_CACHE=<file>overrides it. File name = hash of package version, bundled JRE version, jars (jar_fingerprintsha256 plus each jar's size and mtime), the exact class path (including JPype'sorg.jpype.jar, which the cache records too) and platform.-XX:AOTCacheOutput=<unique tmp>(the JVM writes it when the process exits normally); one trainer at a time via an exclusive lock file holding its pid, other processes start normally. The next start recovers a finished or dead trainer: the bundled JVM must accept the file (-XX:AOTMode=on -version), then an atomic rename and a sidecar with size and sha256. Use is-XX:AOTCache=<file> -XX:AOTMode=auto; a file whose size or sha256 differs from the sidecar is deleted and rebuilt, so a damaged cache is never mapped.arcadedb_embedded.aotlogger;start_jvmnever raises because of it. User-given-XX:AOT*,-XX:SharedArchiveFileor-Xshareflags win and the bindings add nothing.Why
Measured on the laptop with
ab.py(studyjvm-aot-ab-laptop-20261022in the benchmark notes, 12 clean pairs per figure): cold total -33 to -36 percent, JVM start -25 to -30 percent, database open -37 to -42 percent, and no detectable difference in steady-state inserts, lookups or scans. A tiny training run was as good as a broad one. A cache records absolute jar paths and jar mtime and size, so it cannot ship inside the wheel and has to be created on the user's machine.Robustness matrix
Generated from the probe output (
.notes/bench/repros/jvm-aot-robust-20261024:driver.py,child.py,job.sh,job.log,matrix.md). Every repetition is fresh processes and must end with a working database (CHECK ok); "mapped" means the JVM's own-Xlog:aotlog shows it opened and mapped the cache. The probes ran this branch'saot.pyandjvm.pyon top of the merged-main wheel 26.11.1.dev0 (Corretto 25.0.4.1 jre), cores 0-5, through the laptop heavy-job wrapper, with the JVM output kept unfiltered per run.Total: 95 of 95 repetitions passed; SUMMARY runs=514 failed_probe_variants=0
Notes on the cases: probe 2 starts 8 processes at once with no cache, 20 rounds, and then needs two more runs to reach a mapped cache with exactly one cache file and no leftover temp or lock files. Probe 3 damages a good cache six ways plus a missing or garbage sidecar; the damaged file is never mapped and the cache is rebuilt by the third run. Probe 5 used a 1 MB and a 20 MB tmpfs mounted in a user namespace (
unshare -rm, no root) as the cache location, a read-only directory, and a path blocked by a file. Probe 6 has no second JDK on this machine, so an older JRE is simulated by patchingjre_identity(JDK 24, and an unreadablereleasefile). Probe 7 SIGKILLs a training process of the probe itself.Known limit (probe 6, "JVM rejects AOT flag"): if the JVM itself rejects a flag at creation, the start fails with the usual
ArcadeDBErrorand the lock is freed; there is no in-process retry because JPype cannot start a second JVM after a failed one. The flags are only added for a bundled JRE of version 25 or newer, so this is not reachable today, and the probe pins the behaviour.Tests
tests/test_aot.py, 27 tests: key derivation, per-platform cache directory, JRE identity, promotion, damaged caches, stale locks, fallbacks (mocked), override path, off by default. Run withuv run --no-project --with JPype1 --with pytestandPYTHONPATH=src pytest tests/test_aot.py --noconftest(27 passed). The pre-existingtest_log_dir.pyandtest_jvm_args.pysubprocess tests fail in a source tree without jars both on main and on this branch; they pass the same way against the wheel overlay.Still open
ab.pyrun on the release wheel (the study ran on the merged-main wheel).os._exit, SIGKILL) trains nothing, so the next start trains again; a long-lived first process holds the lock and others start without a cache for as long as it lives (or 30 minutes, then the lock is stale).🤖 Generated with Claude Code