feat: add getPinned returning a sealed PinnedResult

[dfa1]

Phase 1 of #47 — additive and non-breaking. No existing signature changes.

The problem, reproduced

Probed against a real DB, 32-byte value into an 8-byte destination:

[buffer]  returned=32  copied=8   content=ABCDEFGH
[segment] returned=32  byteSize=8 content=ABCDEFGH
[segment] present-but-empty=0  absent=0

The ByteBuffer tier is worse than #47 describes: it advances position by the truncated count, so the buffer ends in exactly the state a successful 8-byte read would leave it in — the idiomatic db.get(k, buf); buf.flip(); hands back a clean-looking 8-byte buffer with 24 bytes silently gone. The third line is #44.

The shape

try (PinnedResult result = db.getPinned(key)) {
    switch (result) {
        case PinnedResult.Found found -> consume(found.value());  // MemorySegment
        case PinnedResult.NotFound ignored -> handleMiss();
    }
}

• The length is intrinsic — byteSize() is the value length, and there is no caller-supplied capacity, so insufficient capacity is not a representable state.
• Absence cannot be misread — NotFound carries no length, closing get(MemorySegment, MemorySegment) cannot distinguish "key absent" from "value is empty" #44's gap on this path.
• Expiry is checked — the borrowed segment is scoped to the result; use after close throws IllegalStateException rather than reading freed memory.

AutoCloseable rather than an Arena parameter: a Found pins its block-cache entry until released, and an Arena makes it easy to hand in a long-lived scope, which accumulates pins and presents as native memory growth rather than a heap leak.

Surface

40 overloads across ReadWriteDB, ReadOnlyDB, BlobDB, SecondaryDB, TtlDB, TransactionDB, OptimisticTransactionDB and Transaction — every key tier, ReadOptions variants, CF variants wherever the type has them. One new symbol, rocksdb_transactiondb_get_pinned.

Rule violation fixed en route

rocksdb_pinnableslice_value/_destroy were each mapped three times (RocksDB, Transaction, TransactionDB), against CLAUDE.md's no-duplicate-symbol rule — which names PinnableSlice as the wrapper to build for exactly this.

The copying helpers deliberately do not go through that wrapper: doing so allocated a PinnableSlice + a PinnedResult.Found per read on the hottest path. They use raw-pointer statics that share the same method handles — symbols mapped once, nothing allocated. A pinned read also now opens one confined Arena instead of two.

On reusing one PinnableSlice across many gets

The C++ API documents exactly that, in PinnableSlice; less memcpy with point lookups (RocksDB blog, 24 Aug 2017):

PinnableSlice pinnable_val;
while (!stopped) {
  auto s = db->Get(opt, cf, key, &pinnable_val);
  // ... use it
  pinnable_val.Reset();  // then release it immediately
}

That pattern is not reachable from the C API. Every rocksdb_pinnableslice_t declaration in c.h either returns one or takes one to read/destroy; there is no rocksdb_pinnableslice_create, and nothing accepts a caller-supplied slice to fill. rocksdb_get_pinned does new (rocksdb_pinnableslice_t) per call. rocksdb_get_pinned_v2 claims in its header comment to avoid unnecessary allocations, but its body is byte-for-byte identical.

So reuse could only save the Java side. PinnedReuseBenchmark measures that ceiling — perGet vs everything hoisted out of the loop — parameterized on reads per invocation (1, 2, 8, 32) and value size. What the hoisted variant gives up is the segment's scope, i.e. the protection #45 exists to add.

Correction to prior art

The C++ API has no fixed-capacity destination (db.h:599-640: std::string* grows, PinnableSlice* borrows), so truncation is an artifact the Java binding introduced. The C API, however, has since grown one and got it right (c.h:3583):

/* Returns 1 if value fits in buffer, 0 if buffer too small.
   Sets *vallen to actual value size.
   If buffer is too small, no data is copied but *vallen is set. */
unsigned char rocksdb_get_into_buffer(...);

That is CopyResult in C — including the no-partial-copy behavior #47 recommends and a found out-param that closes #44 — and its PinnableSlice is a stack local, avoiding the per-call new/delete. Phase 3 should be built on it. Details: #47 (comment)

Measurement status: unverified

The allocation changes are defensible on first principles, but every JMH run taken while preparing this was contaminated — a game at ~30% CPU, load average up to 5.8, and a three-fork run 6× slower across the board than single-fork runs minutes earlier.

Retracted: the claimed 1.4–3.5% wrapper-allocation regression, the 18.5% drop on readsMemorySegment, and the 2× advantage for pinned reads on 64 KiB values. No performance claim goes in the README until re-run on an idle machine:

./scripts/benchmark.sh PinnedReadBenchmark
./scripts/benchmark.sh PinnedReuseBenchmark

scripts/benchmark.sh no longer runs mvn install (CLAUDE.md forbids it), uses ./mvnw, and takes an optional class argument.

Testing

21 new tests in GetPinnedTest. 357 → 378 tests, 0 failures. Javadoc clean.

Not in scope

Phase 1 is additive, so the truncating overloads remain and still truncate. Phases 3 and 4 are breaking and belong in one release; #47 stays open.

🤖 Generated with Claude Code

[dfa1]

Two corrections and a benchmark retraction

1. The claim that the C layer has no fixed-capacity destination is out of date.

The description above and the first commit message both say truncation is an artifact the Java binding invented, citing include/rocksdb/db.h:599-640. That remains true of the C++ API — std::string* grows, PinnableSlice* borrows — but the C API has since grown one, and got it right (c.h:3583):

/* Returns 1 if value fits in buffer, 0 if buffer too small.
   Sets *vallen to actual value size.
   If buffer is too small, no data is copied but *vallen is set. */
unsigned char rocksdb_get_into_buffer(..., char* buffer, size_t buffer_size,
                                      size_t* vallen, unsigned char* found, char** errptr);

That is CopyResult in C, including the no-partial-copy behavior #47 recommends, plus a found out-param that closes #44. Details and the verified db/c.cc implementation are in #47 (comment). It doesn't change this PR — phase 1 is still getPinned — but phase 3 should be built on it rather than hand-rolled.

2. PinnableSlice cannot be reused through the C API.

The documented C++ pattern is one caller-owned slice reused across gets with Reset(). Not reachable here: rocksdb_get_pinned does new (rocksdb_pinnableslice_t) per call and c.h exposes no rocksdb_pinnableslice_create. rocksdb_get_pinned_v2, despite a header comment promising it "avoids unnecessary memory allocations", has a byte-for-byte identical body. So one allocation per pinned get is fixed by the interface.

3. Retracting every benchmark number in this PR.

All JMH runs were contaminated — the machine was concurrently running a game at ~30% CPU, opendirectoryd at ~39%, load average 2.47. A three-fork run came back 6× slower across the board than single-fork runs of the same benchmarks taken minutes earlier. That is noise, not signal.

Specifically retracted: the claimed 1.4–3.5% regression from wrapper allocations, the 18.5% drop on readsMemorySegment, and the 2× advantage for pinned reads on 64 KiB values. None of it is trustworthy.

The follow-up commit (44bb587) that those numbers motivated still stands on its own terms — it strictly removes allocations from every copying path, collapses two confined arenas per pinned read into one, and drops an intermediate slice object — but it is labelled unverified, and no performance claim should go in the README until this is re-run on an idle machine.

PinnedReadBenchmark is included here so that re-run is one command: ./scripts/benchmark.sh PinnedReadBenchmark.

[dfa1]

this requires facebook/rocksdb#14984 to avoid creating a new PinnableSlice per key. Without it, this PR cannot progress

[dfa1]

found a better way in #57