Skip to content

Docs: say when to turn on the JVM AOT cache (opt-in, with measured figures) #247

Closed

Description

@tae898

The JVM package (arcadedb-jvm) has an opt-in JDK 25 AOT cache (ARCADEDB_AOT=1 or start_jvm(aot=True), src/arcadedb/aot.py, merged in #31), but no page of the user docs says what it does, when it helps, or what it costs. Only the docstrings of start_jvm mention it.

A timed A/B on one laptop (JDK 25, arcadedb-jvm 26.11.1.dev0, ABBA order, 19 rounds per arm, 18 clean pairs per figure, with an A/A control) decided whether the cache should be the default. It should not: the first script ran faster with the cache (ratio 0.653, 95% interval [0.648, 0.658], first import to first openCypher result), but the steady-state figures showed no gain I can rely on, and the 300,000-row insert_many interval ended at 1.036, above the 1.03 no-harm bar written before the run. So the cache stays opt-in, and the study's rule says to document when to enable it.

The docs should say: what the cache does, how to turn it on and off, when to turn it on (short-lived processes where start-up dominates) and when not to bother (long-running services), the one-time costs (a training run and a cache file on disk), and the measured figures with their intervals, stated as one study on one machine.

I will open a docs-only PR (docs/modules/ROOT/pages/installation.adoc, plus a link from which-package.adoc).

Activity

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions