[tae898]

Closes #213

The JVM wheel crossed into the JVM several times per read. A JPype call is a few microseconds of dispatch, and an untimed async-profiler pass put 10.7% of a warm point-read workload in JNI/libjvm and 5.2% in JPype C++, besides 5.4% of Java glue. This PR cuts the number of crossings of five common calls, each as its own commit, with the answer, the errors and the result-set state unchanged. It is a port of humemai/arcadedb-embedded-python#524 onto main (the layout moved from bindings/python/src/arcadedb_embedded to src/arcadedb; the Java and the Python hunks are otherwise the ones of that branch, re-applied and re-checked against the current code).

What changes (crossings per call, counted by the new tests on a proxy of the Java object and the bridge classes)

• Document.get_raw() (so get(), Vertex.get(), Edge.get()): 2 crossings and 2 scans of the record (has() then get()) become 1 crossing and 1 scan. get() answers null for a property the record does not have, as it does for one set to null, and Python reads None either way; has_property() still tells the two apart.
• ResultSet.one(): RowAccess.upToTwoAndClose returns the first two rows and closes the set in one call, where the loop took hasNext()/next() per row plus the close. Zero rows, several rows, an error while reading and a closed database raise the same exceptions and leave the same _closed/_exhausted state as the plain path, which stays for a missing bridge class.
• ResultSet.count(): RowAccess.countAndClose counts the rows left and drains and closes the set in one call, where the loop crossed twice per row. A statement error surfaces as before.
• Database.lookup_by_key(): it was already one crossing, but built a String[] and an Object[] through JPype first. DbCalls.lookupFirstKey takes one key as scalars and lookupFirstKeys takes any number as the varargs of one call (names then values, so a different number of names and values reaches the engine as before). lookupFirst, which takes the arrays, stays.
• The transaction-stack mark taken before every begin(): DbCalls.stackMark returns active and nesting depth as one number, so with db.transaction() goes from 4 crossings to 3 and run_in_transaction() from 6 to 5. The mark is still taken before begin(), so the interrupt and refused-begin rules of #9970, #9813 and #7916 are unchanged.

The native backend is not touched: nothing under src/arcadedb/_native or native/ changes, and tests/test_read_crossings.py is listed in NATIVE_NOT_APPLICABLE because it counts JPype crossings.

Tests tests/test_read_crossings.py (21 tests, added with the commit each belongs to): crossing counts plus equivalence with the plain path, including typed and composite keys, error cases and the engine's own stack numbers. The counts fail on main and the equivalence tests pass on both. Run in CI against the wheel built from this branch (the bridge jar is rebuilt there); nothing was run on the author's laptop, so CI is the first run of this port.

What was measured A pre-registered timed A/B of this branch's JVM wheel against main's under concurrency (A/A control, rule written before the run) shipped by its rule: figures, intervals and scope in this comment and in the new docs section. The earlier timed A/B without threads ended with too few clean pairs for a verdict, so nothing from it is reported.

Docs: how-to/concurrency.adoc has a section with the concurrency figures of the timed study (mixed window at 2 Python threads on arcadedb-jvm, with the 1-thread row, the reader and writer shares, the control and what was not measured), added in ab15053.

🤖 Generated with Claude Code

Edited 2026-11-05: the status line now gives the timed result; the PR is ready for review.

[tae898]

Timed A/B of this PR under concurrency on the JVM wheel (laptop timed lane, two timed cores, tools/ab.py --noise, ABBA order, round 0 dropped, an A/A control). Arm A = the main CI JVM wheel 413f54ffe1, arm B = this PR's head bfe397b0c2. Time per operation, B/A median with its 95% interval (below 1 = this PR is faster):

workload	role	B/A median [95% CI]	A/A median [95% CI]
mixed window, 2 Python threads (one reader, one writer)	gating	0.489 [0.475, 0.499]	0.987 [0.960, 1.006]
mixed window, 1 thread	guard	0.510 [0.507, 0.514]	0.988 [0.974, 1.014]
control: Cypher 2-hop count and .first() readers with a writer (changed only by one crossing per writer transaction), 2 threads	control	1.016 [0.978, 1.037]	1.007 [0.967, 1.038]
reader's share of the 2-thread window	info	0.476 [0.461, 0.487]	0.986 [0.957, 1.007]
writer's share of the 2-thread window	info	0.992 [0.945, 1.007]	0.990 [0.965, 1.012]

Clean pairs per figure: 10. By the rule written before the run (gating upper end below 0.98, the 1-thread guard not clearly worse, the control median inside [0.97, 1.03], a clean A/A) this is a SHIP: the mixed window costs 0.489 [0.475, 0.499] of main's time at 2 threads, the gain is in the reader's share (0.476 [0.461, 0.487]), and the control stays inside its band.

The single-thread study of the same head (TA-3) ended WEAK at its round cap, because its transaction-commit figure could not narrow enough on a busy laptop, so it reports nothing; the claim above rests on this study alone. The PR leaves draft at the end of the current batch of timed studies that pin main, with its docs, and merges on green. I can re-run either study on the branch after any change.