Skip to content

Proposal: a database close() waits for calls in flight on other threads - #348

Draft
dfa1 wants to merge 2 commits into
mainfrom
inflight-call-guard
Draft

dfa1 wants to merge 2 commits into
mainfrom
inflight-call-guard

Conversation

@dfa1

@dfa1 dfa1 commented Nov 15, 2026

Copy link
Copy Markdown
Owner

What and why

Draft: a prototype to decide on, not ready to merge.

Closing a database while another thread is inside a call on it crashes the JVM today. Reproduced in forked JVMs (eight threads against a close, 400 open/close rounds):

Racing call main This branch (3 runs each)
iterator scan (seekToFirst / next / value) SIGSEGV in rocksdb_iter_next survived
compactRange() SIGSEGV in rocksdb::EnvLogger::FlushLocked survived
get(byte[]), put(byte[], byte[]) survived (narrower window, not safe) survived

This is the close-versus-call window docs/explanation.md documents. #342 could refuse a close from inside a callback because the caller is on the closing thread's own stack; here the caller is on another thread, so close() needs shared state.

How

  • NativeDB holds a counter of calls in flight, striped per thread (64 padded slots in an AtomicLongArray) so threads sharing a database do not contend on one cache line.
  • A guarded call does enter() (raise the counter, then check the pointer) and exit() in a finally.
  • close() swaps the pointer to NULL, then waits for the counters to drain, then releases children and the database. The counter is raised before the pointer is read and the pointer is swapped before the counters are read, so one side always sees the other: either the call throws IllegalStateException, or the close waits for it.
  • Iterator calls count against their database, so the close no longer frees an iterator another thread is inside.

Behaviour change: close() blocks until in-flight calls return.

Cost

JMH on an Apple M5, 2 forks, main against this branch:

Benchmark main This branch Change
FfmBenchmark.readsBytes 131 ns 143 ns -8% (error ±3%)
FfmBenchmark.readsMemorySegment 136 ns 139 ns within error
FfmBenchmark.readsInstantViaPinned 113 ns 109 ns within error
FfmBenchmark.writesBytesNoWal 272 ns 266 ns within error
FfmScaleBenchmark.iterateByteArray 65 ns per entry 74 ns -12%
FfmScaleBenchmark.iterateZeroCopy 58 ns per entry 65 ns -11%

Scans are the real cost: about 7 to 9 ns per entry, since each entry makes three guarded calls. Four threads sharing one database (SharedDbReadBenchmark, added here) was inconclusive: run-to-run error was ±12 to 20%, larger than any effect of the guard.

Open questions

  • Is about 10% on iterator scans acceptable? The alternative is to guard database calls only and leave iterators on today's rule.
  • Wait or throw? close() currently waits; a thread in a long compactRange() holds it until it returns.
  • Coverage is partial. Guarded: 48 methods in the four RocksDB*OperationsBindings classes, plus RocksIterator. Not guarded yet: TransactionDB's own calls, Transaction and its iterators, ReadBatch, ingestExternalFile, and a few tracing and monitoring calls.
  • Only the database is guarded. Closing a ReadOptions or WriteOptions that another thread is passing to a call is still a race.
  • The bindings cast their capability interface to NativeDB to reach the guard; a finished version needs a cleaner seam.
  • No docs or ADR yet.

Checklist

  • Tests use JUnit 5 + AssertJ with @TempDir, Given / When / Then (CloseWaitsForInFlightCallsTest)
  • ./mvnw test -pl core -am passes
  • ./mvnw package -pl core,benchmarks -am -DskipTests passes
  • New native bindings: none
  • CHANGELOG.md: left for the maintainer
  • Docs: pending the decision

🤖 Generated with Claude Code

dfa1 and others added 2 commits November 15, 2026 17:28
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Each guarded call raises a per-thread striped counter on its database before reading the pointer;
close() swaps the pointer, waits for the counters to drain, then releases children and the database.
Prototype: covers the four Bindings classes and RocksIterator, not TransactionDB, Transaction or ReadBatch.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@dfa1 dfa1 added the enhancement New feature or request label Nov 15, 2026

This branch has not been deployed

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

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant