From ffc0f5b601240e23718277c112bd2db6f07060d4 Mon Sep 17 00:00:00 2001 From: Davide Angelocola Date: Mon, 16 Nov 2026 09:05:51 +0100 Subject: [PATCH 1/5] Normalize the close protocol: close() -> release() -> tryClose() doRelease, afterRelease, NativeObjectParent's final tryClose with tryCloseResource, and NativeDBWithBaseDB's tryCloseBaseDb/tryClosePrimary hooks are gone. A parent's own tryClose starts with releaseChildren(); NativeObjectChild.release() adds the monitor and the unregistration around NativeObject.release(). Refs #354. Co-Authored-By: Claude Sonnet 5 --- .../io/github/dfa1/rocksdbffm/EnvOptions.java | 3 +- .../io/github/dfa1/rocksdbffm/NativeDB.java | 3 +- .../dfa1/rocksdbffm/NativeDBWithBaseDB.java | 43 +++------------- .../github/dfa1/rocksdbffm/NativeObject.java | 31 +++++------ .../dfa1/rocksdbffm/NativeObjectChild.java | 49 ++++++++---------- .../dfa1/rocksdbffm/NativeObjectParent.java | 51 +++++++------------ .../rocksdbffm/OptimisticTransactionDB.java | 13 ++--- .../github/dfa1/rocksdbffm/ReadOptions.java | 3 +- .../github/dfa1/rocksdbffm/Transaction.java | 7 +-- .../github/dfa1/rocksdbffm/TransactionDB.java | 13 ++--- .../rocksdbffm/NativeObjectParentTest.java | 18 ++++--- docs/reference.md | 4 +- 12 files changed, 95 insertions(+), 143 deletions(-) diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/EnvOptions.java b/core/src/main/java/io/github/dfa1/rocksdbffm/EnvOptions.java index a695ef15..d9b9166a 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/EnvOptions.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/EnvOptions.java @@ -351,7 +351,8 @@ public EnvOptions setRateLimiter(RateLimiter rateLimiter) { } @Override - protected void tryCloseResource(MemorySegment ptr) throws Throwable { + protected void tryClose(MemorySegment ptr) throws Throwable { + releaseChildren(); MH_DESTROY.invokeExact(ptr); } } diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/NativeDB.java b/core/src/main/java/io/github/dfa1/rocksdbffm/NativeDB.java index 17b9c3de..2ccf935f 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/NativeDB.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/NativeDB.java @@ -69,7 +69,8 @@ public void close() { } @Override - protected void tryCloseResource(MemorySegment ptr) throws Throwable { + protected void tryClose(MemorySegment ptr) throws Throwable { + releaseChildren(); MH_CLOSE.invokeExact(ptr); } diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/NativeDBWithBaseDB.java b/core/src/main/java/io/github/dfa1/rocksdbffm/NativeDBWithBaseDB.java index 57366dbf..4d007739 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/NativeDBWithBaseDB.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/NativeDBWithBaseDB.java @@ -9,18 +9,18 @@ /// /// Per `rocksdb/db/c.cc`, each `get_base_db` call heap-allocates a small `rocksdb_t` wrapper /// struct (`{ DB* rep; }`) around the already-owned database object — a distinct allocation -/// from the database itself. [#tryCloseBaseDb(MemorySegment)] frees only that wrapper, +/// from the database itself. A subclass's [#tryClose(MemorySegment)] frees only that wrapper, /// best-effort (a failure there does not prevent the primary pointer from still being closed); -/// it neither destroys nor can destroy the real database object, which the primary handle's own -/// close ([#tryClosePrimary(MemorySegment)], run afterward) already owns and destroys. +/// it neither destroys nor can destroy the real database object, which the primary close, run +/// afterward, already owns and destroys. /// -/// The base DB pointer is private to this class — subclasses have no name for it, so they -/// cannot accidentally read it unchecked. The only access is [#dbPtr()], which calls [#ptr()] -/// first and therefore throws [IllegalStateException] once this object is closed, the same way -/// every other native call on this object already does. +/// The base DB pointer is read unchecked only from `tryClose`, where the guard of [#ptr()] has already been +/// consumed. Everything else goes through [#dbPtr()], which calls [#ptr()] first and therefore throws +/// [IllegalStateException] once this object is closed, the same way every other native call on this object +/// already does. abstract class NativeDBWithBaseDB extends NativeDB { - private final MemorySegment baseDb; + final MemorySegment baseDb; protected NativeDBWithBaseDB(MemorySegment ptr, MemorySegment baseDb) { super(ptr); @@ -37,31 +37,4 @@ public final MemorySegment dbPtr() { ptr(); return baseDb; } - - @Override - protected final void tryCloseResource(MemorySegment ptr) throws Throwable { - try { - tryCloseBaseDb(baseDb); - } catch (Throwable _) { - // best-effort: still attempt to close the primary pointer below - } - tryClosePrimary(ptr); - } - - /// Frees the small `rocksdb_t` wrapper struct that [#dbPtr()] returns, for subclasses whose - /// C API exposes a matching close call (e.g. `rocksdb_optimistictransactiondb_close_base_db`). - /// This does not touch the underlying database object itself — only - /// [#tryClosePrimary(MemorySegment)] does that, via its own teardown. Default: no-op. - /// - /// @param baseDb the base DB pointer to release - /// @throws Throwable if the native destroy call fails - protected void tryCloseBaseDb(MemorySegment baseDb) throws Throwable { - // no separate close needed by default - } - - /// Closes the primary native pointer. Same contract as [NativeObject#tryClose(MemorySegment)]. - /// - /// @param ptr the non-NULL primary native pointer to release - /// @throws Throwable if the native destroy call fails - protected abstract void tryClosePrimary(MemorySegment ptr) throws Throwable; } diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObject.java b/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObject.java index 5780ab8d..77d2ea91 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObject.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObject.java @@ -71,19 +71,18 @@ final boolean isClosed() { } /// Releases the native resource, unless this object is immortal. A wrapper that is released by its owner and - /// not by whoever holds it (a [ColumnFamilyHandle]) overrides this as a no-op; `release()` - /// still frees it. + /// not by whoever holds it (a [ColumnFamilyHandle]) overrides this as a no-op; `release()` still frees it. /// /// Returns at once if another thread is already releasing this object, instead of waiting for it: only a - /// parent's sweep needs that wait, and it goes through `release()`. A native release can block - /// on a callback thread (`rocksdb_close` draining an event listener), and a `close()` from that callback would - /// otherwise deadlock. + /// parent's sweep needs that wait, and a [NativeObjectChild] gives it that in `release()`. A native release can + /// block on a callback thread (`rocksdb_close` draining an event listener), and a `close()` from that callback + /// would otherwise deadlock. @Override public void close() { if (immortal || isClosed()) { return; } - doRelease(); + release(); } /// @return `true` if [#makeImmortal()] was called, so [#close()] does nothing @@ -91,9 +90,11 @@ final boolean isImmortal() { return immortal; } - /// Swaps the pointer to NULL and, if this call won that swap, runs [#tryClose(MemorySegment)] and then - /// [#afterRelease()]. Idempotent and never throws. - final void doRelease() { + /// Swaps the pointer to NULL and, if this call won that swap, runs [#tryClose(MemorySegment)], logging + /// instead of throwing. Idempotent and never throws. Whatever [#close()] would otherwise do: the entry point for + /// an owner that frees an object whose `close()` is a no-op. A [NativeObjectChild] overrides it to add the + /// monitor a parent's sweep waits on, and its unregistration from the parents. + void release() { MemorySegment ptr = (MemorySegment) OWNING_POINTER.getAndSet(this, MemorySegment.NULL); if (!MemorySegment.NULL.equals(ptr)) { try { @@ -103,19 +104,13 @@ final void doRelease() { // try-with-resources chain from closing — but a failure to release a native // resource is still worth knowing about. LOG.log(System.Logger.Level.ERROR, getClass().getSimpleName() + ".close() failed", throwable); - } finally { - afterRelease(); } } } - /// Hook run last in [#doRelease()], after the native release call. A [NativeObjectChild] unregisters from its - /// owners here. - void afterRelease() { - } - - /// Called exactly once with the non-NULL pointer when this object is closed. - /// Implementations must release the native resource. + /// Called exactly once with the non-NULL pointer when this object is closed. Implementations release everything + /// this object owns, in the order it needs: a [NativeObjectParent] starts with `releaseChildren()`, so no child's + /// release runs against memory this object has already freed. /// /// A [NativeObjectChild] runs it while holding its own monitor, so an implementation must never close, release or /// lock another [NativeObject] that could be one of its owners: owners are locked before the objects that diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectChild.java b/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectChild.java index 006d03aa..1e3406d5 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectChild.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectChild.java @@ -8,7 +8,7 @@ abstract class NativeObjectChild extends NativeObject { /// The objects this one borrows native memory from, set once by [#childOf(NativeObjectParent)] or - /// [#childOf(NativeObjectParent, NativeObjectParent)]; [#afterRelease()] unregisters from them after the native + /// [#childOf(NativeObjectParent, NativeObjectParent)]; `release()` unregisters from them after the native /// release call. Plain fields: they are assigned before the registration that publishes this object to a /// parent's sweep, and that registration is what makes the writes visible to the sweeping thread. private NativeObjectParent parent; @@ -23,7 +23,7 @@ protected NativeObjectChild(MemorySegment owningPointer) { } /// Declares that this object borrows native memory from `parent`: it is registered as its child, so the parent's close releases it first, and - /// [#afterRelease()] unregisters it when it is closed on its own, so a long-lived parent does not accumulate every + /// its release unregisters it when it is closed on its own, so a long-lived parent does not accumulate every /// child it ever produced. Call it once, last in the constructor, once every field /// [#tryClose(MemorySegment)] reads is assigned, because registering makes this object visible to a concurrent /// sweep by a parent. @@ -38,7 +38,7 @@ final void childOf(NativeObjectParent parent) { } /// Declares that this object borrows native memory from both parents (a [RocksIterator] has its database and its [ReadOptions]): it is registered as a child of each, so either one's close releases it first, and - /// [#afterRelease()] unregisters it when it is closed on its own, so a long-lived parent does not accumulate every + /// its release unregisters it when it is closed on its own, so a long-lived parent does not accumulate every /// child it ever produced. Call it once, last in the constructor, once every field /// [#tryClose(MemorySegment)] reads is assigned, because registering makes this object visible to a concurrent /// sweep by a parent. @@ -62,40 +62,31 @@ final void childOf(NativeObjectParent first, NativeObjectParent second) { } } - /// Releases the native resource exactly once, whatever [#close()] would otherwise do: the entry point for the - /// owning [NativeObjectParent] to free a child whose [#close()] is a no-op. Idempotent and never throws. + /// [NativeObject#release()] under this object's monitor, then unregisters from the parents. /// /// A call that loses the race to another thread already releasing this object blocks until that release has /// finished, instead of returning at once: a parent's sweep calls this on each child and then frees its own /// pointer, so returning early would let the parent be destroyed while a child, released by another thread, is /// still using it. Parents are always locked before their children and [#tryClose(MemorySegment)] never locks a /// parent, so the wait cannot deadlock. + /// + /// Unregistering comes last: a parent that starts closing while this release is still running must still find + /// this object in its children, so its sweep waits on the monitor instead of freeing the parent under a native + /// release in progress. When this runs because that parent's own sweep is releasing its children, its pointer + /// stays valid until the sweep ends. Unregistering is idempotent, so a call that lost the race repeats it harmlessly. + @Override final void release() { synchronized (lock) { - doRelease(); - } - } - - /// Releases through `release()` so an in-progress release is still observed by a sweep waiting on the monitor. - @Override - public void close() { - if (isImmortal() || isClosed()) { - return; - } - release(); - } - - /// Unregisters from every parent. Runs last in `release()`: a parent that starts closing while this - /// release is still running must still find this object in its children, so its sweep waits on the monitor - /// instead of freeing the parent under a native release in progress. When this runs because that parent's own - /// sweep is releasing its children, its pointer stays valid until the sweep ends. - @Override - final void afterRelease() { - if (parent != null) { - parent.unregisterChild(this); - } - if (secondParent != null) { - secondParent.unregisterChild(this); + try { + super.release(); + } finally { + if (parent != null) { + parent.unregisterChild(this); + } + if (secondParent != null) { + secondParent.unregisterChild(this); + } + } } } } diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectParent.java b/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectParent.java index 7a58bf60..1ab9168e 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectParent.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectParent.java @@ -11,12 +11,11 @@ /// needs its owning DB's pointer) — and would otherwise dangle if this object closed first. /// /// A child registers itself with [NativeObjectChild#childOf(NativeObjectParent)], last in its own -/// constructor, and [NativeObjectChild#afterRelease()] unregisters it once released on its own, so a long-lived parent +/// constructor, and [NativeObjectChild]'s release unregisters it once released on its own, so a long-lived parent /// doesn't accumulate strong references to every child it ever produced. -/// [#tryClose(MemorySegment)] closes every still-registered child, synchronously, while `ptr` -/// is still valid — before delegating to [#tryCloseResource(MemorySegment)] for this object's -/// own native destroy call — so a child's release call never runs against memory this object -/// has already freed, whichever side closes first. +/// A parent's [#tryClose(MemorySegment)] starts with [#releaseChildren()], which closes every still-registered +/// child, synchronously, while `ptr` is still valid — before its own native destroy call — so a child's release +/// call never runs against memory this object has already freed, whichever side closes first. /// /// [#registerChild(NativeObjectChild)] is lock-free — see its doc for the TOCTOU race it narrows /// (issues/143): a child's native "create" call can succeed an instant before this object @@ -77,7 +76,7 @@ protected NativeObjectParent(MemorySegment ptr) { /// [NativeObject#transferOwnership()] -- a real native resource leak, of everything its release would have freed /// (the native object and any native memory the wrapper owns, such as an iterator's length slot; its release call would /// itself be a use-after-free against a pointer this object's own - /// [#tryCloseResource(MemorySegment)] may already have freed), but not the JVM crash a later + /// [#tryClose(MemorySegment)] may already have freed), but not the JVM crash a later /// use of a silently-dangling `child` would otherwise risk. If the removal instead finds /// `child` already gone, the sweep won the race and already closed it properly (through the /// normal path below, while `ptr` was still valid) -- nothing left to do. @@ -124,6 +123,12 @@ final void unregisterChild(NativeObjectChild child) { /// transaction's iterators on commit) without destroying its parent. /// /// @param type the kind of child to release + /// + /// A parent's [#tryClose(MemorySegment)] calls [#releaseChildren()] first. `release()` is safe on a child whether + /// or not its own caller already closed it, and `children` is a [ConcurrentHashMap]-backed set, so a child + /// unregistering itself mid-iteration does not throw. Nothing is cleared afterward: every `release()` already + /// unregisters its child, so a sweep drains the set on its own; anything left is a `registerChild` made during + /// this very sweep, which that call's own recheck cleans up. final void releaseChildren(Class type) { Set set = children; if (set == null) { @@ -136,37 +141,15 @@ final void releaseChildren(Class type) { } } + /// Releases every still-registered child, synchronously: the first step of a parent's + /// [#tryClose(MemorySegment)], while its own pointer is still valid. + final void releaseChildren() { + releaseChildren(NativeObjectChild.class); + } + /// @return how many children are registered right now, for tests asserting that a closed child unregistered final int childCount() { Set set = children; return set == null ? 0 : set.size(); } - - @Override - protected final void tryClose(MemorySegment ptr) throws Throwable { - // child.release() is safe to call whether or not the child was already closed by its own - // caller (NativeObject's release() is idempotent), and children is a ConcurrentHashMap- - // backed set, so a child unregistering itself mid-iteration does not throw - // ConcurrentModificationException. No children.clear() afterward: every child.release() - // call above already unregisters that child from `children` (see NativeObjectChild#release()), - // so a normal sweep already drains the set on its - // own; anything still present after this loop is exactly the registerChild-added-during- - // this-very-sweep stragglers described there, and registerChild's own recheck cleans - // those up (whether that happens before or after this method returns). - Set set = children; - if (set != null) { - for (NativeObjectChild child : set) { - child.release(); - } - } - tryCloseResource(ptr); - } - - /// Closes this object's own native resource. Same contract as - /// [NativeObject#tryClose(MemorySegment)] — renamed only because `tryClose` itself is - /// final here, to guarantee children are always closed first. - /// - /// @param ptr the non-NULL primary native pointer to release - /// @throws Throwable if the native destroy call fails - protected abstract void tryCloseResource(MemorySegment ptr) throws Throwable; } diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/OptimisticTransactionDB.java b/core/src/main/java/io/github/dfa1/rocksdbffm/OptimisticTransactionDB.java index 69e526b7..ebc8bc4f 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/OptimisticTransactionDB.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/OptimisticTransactionDB.java @@ -89,12 +89,13 @@ public Transaction beginTransaction(WriteOptions writeOptions, OptimisticTransac // ----------------------------------------------------------------------- @Override - protected void tryCloseBaseDb(MemorySegment baseDb) throws Throwable { - MH_CLOSE_BASE_DB.invokeExact(baseDb); - } - - @Override - protected void tryClosePrimary(MemorySegment ptr) throws Throwable { + protected void tryClose(MemorySegment ptr) throws Throwable { + releaseChildren(); + try { + MH_CLOSE_BASE_DB.invokeExact(baseDb); + } catch (Throwable _) { + // best-effort: still close the primary pointer below + } MH_CLOSE.invokeExact(ptr); } } diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/ReadOptions.java b/core/src/main/java/io/github/dfa1/rocksdbffm/ReadOptions.java index ab576419..35e1eaaf 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/ReadOptions.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/ReadOptions.java @@ -485,7 +485,8 @@ MemorySegment readPtr() { } @Override - protected void tryCloseResource(MemorySegment ptr) throws Throwable { + protected void tryClose(MemorySegment ptr) throws Throwable { + releaseChildren(); MH_DESTROY.invokeExact(ptr); } } diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/Transaction.java b/core/src/main/java/io/github/dfa1/rocksdbffm/Transaction.java index b0565b3d..caf538e1 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/Transaction.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/Transaction.java @@ -849,7 +849,7 @@ public void commit() { MemorySegment err = NativeCalls.errHolder(arena); MH_COMMIT.invokeExact(ptr(), err); NativeCalls.checkError(err); - releaseChildren(NativeObjectChild.class); + releaseChildren(); } catch (Throwable t) { throw NativeCalls.wrapInvokeFailure("transaction commit failed", t); } @@ -862,7 +862,7 @@ public void rollback() { MemorySegment err = NativeCalls.errHolder(arena); MH_ROLLBACK.invokeExact(ptr(), err); NativeCalls.checkError(err); - releaseChildren(NativeObjectChild.class); + releaseChildren(); } catch (Throwable t) { throw NativeCalls.wrapInvokeFailure("transaction rollback failed", t); } @@ -894,7 +894,8 @@ public void rollbackToSavePoint() { /// call [#commit()] or [#rollback()] first: anything uncommitted is discarded. Its iterators are /// closed first, and a transaction closed on its own stops being tracked by its database. @Override - protected void tryCloseResource(MemorySegment ptr) throws Throwable { + protected void tryClose(MemorySegment ptr) throws Throwable { + releaseChildren(); MH_DESTROY.invokeExact(ptr); } diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/TransactionDB.java b/core/src/main/java/io/github/dfa1/rocksdbffm/TransactionDB.java index 70708bfe..d02e2841 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/TransactionDB.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/TransactionDB.java @@ -1058,12 +1058,13 @@ public OptionalLong getLongProperty(ColumnFamilyHandle cf, Property property) { // ----------------------------------------------------------------------- @Override - protected void tryCloseBaseDb(MemorySegment baseDb) throws Throwable { - MH_CLOSE_BASE_DB.invokeExact(baseDb); - } - - @Override - protected void tryClosePrimary(MemorySegment ptr) throws Throwable { + protected void tryClose(MemorySegment ptr) throws Throwable { + releaseChildren(); + try { + MH_CLOSE_BASE_DB.invokeExact(baseDb); + } catch (Throwable _) { + // best-effort: still close the primary pointer below + } MH_CLOSE.invokeExact(ptr); } diff --git a/core/src/test/java/io/github/dfa1/rocksdbffm/NativeObjectParentTest.java b/core/src/test/java/io/github/dfa1/rocksdbffm/NativeObjectParentTest.java index 3ca48b53..5c933292 100644 --- a/core/src/test/java/io/github/dfa1/rocksdbffm/NativeObjectParentTest.java +++ b/core/src/test/java/io/github/dfa1/rocksdbffm/NativeObjectParentTest.java @@ -23,15 +23,16 @@ class NativeObjectParentTest { private static final class TestParent extends NativeObjectParent { - final AtomicInteger tryCloseResourceCount = new AtomicInteger(); + final AtomicInteger tryCloseCount = new AtomicInteger(); TestParent(MemorySegment ptr) { super(ptr); } @Override - protected void tryCloseResource(MemorySegment ptr) { - tryCloseResourceCount.incrementAndGet(); + protected void tryClose(MemorySegment ptr) { + releaseChildren(); + tryCloseCount.incrementAndGet(); } } @@ -65,7 +66,7 @@ void registerChild_beforeParentCloses_isClosedByParentSweep() { // Then assertThat(child.tryCloseCount).hasValue(1); - assertThat(parent.tryCloseResourceCount).hasValue(1); + assertThat(parent.tryCloseCount).hasValue(1); } @Test @@ -179,7 +180,8 @@ void parentClose_whileAnotherThreadIsStillClosingAChild_waitsForTheChild() throw var childMayFinish = new CountDownLatch(1); var parent = new NativeObjectParent(fakePtr(0x1)) { @Override - protected void tryCloseResource(MemorySegment ptr) { + protected void tryClose(MemorySegment ptr) { + releaseChildren(); order.add("parent"); } }; @@ -322,13 +324,15 @@ void grandparentClose_whileAChildIsStillSweepingItsOwnChildren_waitsForTheChild( var grandchildMayFinish = new CountDownLatch(1); var grandparent = new NativeObjectParent(fakePtr(0x1)) { @Override - protected void tryCloseResource(MemorySegment ptr) { + protected void tryClose(MemorySegment ptr) { + releaseChildren(); order.add("grandparent"); } }; var child = new NativeObjectParent(fakePtr(0x2)) { @Override - protected void tryCloseResource(MemorySegment ptr) { + protected void tryClose(MemorySegment ptr) { + releaseChildren(); order.add("child"); } }; diff --git a/docs/reference.md b/docs/reference.md index f0e3c7b9..b9c64193 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -503,8 +503,8 @@ return `null` to run that compaction with no filter at all. | `RocksDBException`| Unchecked; thrown for a genuine RocksDB-reported error (see [explanation.md#errors-are-always-loud](explanation.md#errors-are-always-loud)) | | `NativeObject` | Base class of every native wrapper; `ptr()`, `close()` (idempotent), abstract `tryClose` | | `NativeObjectChild` | `NativeObject` subclass for wrappers that borrow native memory from an owner (`RocksIterator`, `Snapshot`, `ColumnFamilyHandle`, ...); `childOf(owners)` registers it so the owner closes it first | -| `NativeObjectParent` | `NativeObjectChild` subclass for wrappers that can produce children borrowing their pointer (every DB type producing `Snapshot`/`RocksIterator`); children register with `NativeObjectChild#childOf`, closes children before `tryCloseResource` — see [explanation.md](explanation.md#lifecycle-and-ownership) | -| `NativeDBWithBaseDB` | `NativeObjectParent` subclass for wrappers with a second owned pointer (`TransactionDB`/`OptimisticTransactionDB`'s `rocksdb_t*` "base DB"); guarded `dbPtr()`, hooks `tryCloseBaseDb`/`tryClosePrimary` — see [explanation.md](explanation.md#lifecycle-and-ownership) | +| `NativeObjectParent` | `NativeObjectChild` subclass for wrappers that can produce children borrowing their pointer (every DB type producing `Snapshot`/`RocksIterator`); children register with `NativeObjectChild#childOf`, its `tryClose` starts with `releaseChildren()` — see [explanation.md](explanation.md#lifecycle-and-ownership) | +| `NativeDBWithBaseDB` | `NativeObjectParent` subclass for wrappers with a second owned pointer (`TransactionDB`/`OptimisticTransactionDB`'s `rocksdb_t*` "base DB"); guarded `dbPtr()`, `baseDb` read only by `tryClose` — see [explanation.md](explanation.md#lifecycle-and-ownership) | `Path` is used for every filesystem argument; there is no `String` path overload anywhere. From 7ec102e1de9f42f0427df4972d1e0f5c0439e92b Mon Sep 17 00:00:00 2001 From: Davide Angelocola Date: Tue, 17 Nov 2026 07:55:19 +0100 Subject: [PATCH 2/5] NativeObjectParent keeps an eager concurrent children set Drops the lazily created set (volatile field, VarHandle CAS, null checks): it saved two small objects on four parent classes. Also fixes stale AtomicReference wording. Co-Authored-By: Claude Sonnet 5 --- .../dfa1/rocksdbffm/NativeObjectParent.java | 64 +++++-------------- 1 file changed, 17 insertions(+), 47 deletions(-) diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectParent.java b/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectParent.java index 1ab9168e..9fa7ea3d 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectParent.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectParent.java @@ -1,8 +1,6 @@ package io.github.dfa1.rocksdbffm; import java.lang.foreign.MemorySegment; -import java.lang.invoke.MethodHandles; -import java.lang.invoke.VarHandle; import java.util.Set; import java.util.concurrent.ConcurrentHashMap; @@ -22,26 +20,13 @@ /// closes, racing its own constructor's `registerChild` call against the one-shot sweep. Rather /// than a lock around the check, `registerChild` inserts optimistically and validates /// afterward, undoing if the validation says it shouldn't have happened — an "insert, recheck, -/// compensate" pattern that needs nothing beyond [NativeObject]'s existing `AtomicReference` -/// and [ConcurrentHashMap]'s own atomic add/remove. +/// compensate" pattern that needs nothing beyond [NativeObject]'s volatile pointer (the recheck reads it through +/// [NativeObject#isClosed()]) and [ConcurrentHashMap]'s own atomic add/remove. abstract class NativeObjectParent extends NativeObjectChild { - private static final VarHandle CHILDREN; - - static { - try { - CHILDREN = MethodHandles.lookup().findVarHandle(NativeObjectParent.class, "children", Set.class); - } catch (ReflectiveOperationException e) { - throw new ExceptionInInitializerError(e); - } - } - - /// Created by the first [#registerChild(NativeObjectChild)], so an instance that never gets a child (most - /// [ReadOptions] and [EnvOptions]) allocates no set at all. Readers treat `null` as empty: a sweep that reads - /// `null` started before any registration published a set, and that registration's own recheck of - /// [#isClosed()] (see [#registerChild(NativeObjectChild)]) sees this object already closed, because [#close()] - /// nulls the pointer before the sweep runs. - private volatile Set children; + /// A concurrent set, never behind a lock: [#unregisterChild(NativeObjectChild)] runs inside a child's own monitor + /// while a sweep calls into the children, so a lock here would deadlock against them. + private final Set children = ConcurrentHashMap.newKeySet(); protected NativeObjectParent(MemorySegment ptr) { super(ptr); @@ -84,7 +69,7 @@ protected NativeObjectParent(MemorySegment ptr) { /// Both outcomes of a "child visited by the sweep" and "child abandoned here" landing on the /// very same instance at once are safe regardless of which wins: [NativeObject#close()] and /// [NativeObject#transferOwnership()] both just (idempotently) null the same - /// `AtomicReference`, so whichever runs second is a no-op. + /// pointer field, so whichever runs second is a no-op. /// /// @param child the child resource to close alongside (and before) this object final void registerChild(NativeObjectChild child) { @@ -92,15 +77,8 @@ final void registerChild(NativeObjectChild child) { // Never swept, so tracking the child would only pin it for the life of the JVM. return; } - Set set = children; - if (set == null) { - Set fresh = ConcurrentHashMap.newKeySet(); - @SuppressWarnings("unchecked") - Set witness = (Set) CHILDREN.compareAndExchange(this, null, fresh); - set = witness == null ? fresh : witness; - } - set.add(child); - if (isClosed() && set.remove(child)) { + children.add(child); + if (isClosed() && children.remove(child)) { child.transferOwnership(); } } @@ -112,29 +90,22 @@ final void registerChild(NativeObjectChild child) { /// /// @param child the child resource to stop tracking final void unregisterChild(NativeObjectChild child) { - Set set = children; - if (set != null) { - set.remove(child); - } + children.remove(child); } /// Releases every still-registered child of the given type, leaving this object and its other /// children open — for a native call that invalidates one kind of borrowed object (e.g. a /// transaction's iterators on commit) without destroying its parent. /// - /// @param type the kind of child to release - /// /// A parent's [#tryClose(MemorySegment)] calls [#releaseChildren()] first. `release()` is safe on a child whether - /// or not its own caller already closed it, and `children` is a [ConcurrentHashMap]-backed set, so a child - /// unregistering itself mid-iteration does not throw. Nothing is cleared afterward: every `release()` already - /// unregisters its child, so a sweep drains the set on its own; anything left is a `registerChild` made during - /// this very sweep, which that call's own recheck cleans up. + /// or not its own caller already closed it, and a child unregistering itself mid-iteration does not throw. + /// Nothing is cleared afterward: every `release()` already unregisters its child, so a sweep drains the set on + /// its own; anything left is a `registerChild` made during this very sweep, which that call's own recheck cleans + /// up. + /// + /// @param type the kind of child to release final void releaseChildren(Class type) { - Set set = children; - if (set == null) { - return; - } - for (NativeObjectChild child : set) { + for (NativeObjectChild child : children) { if (type.isInstance(child)) { child.release(); } @@ -149,7 +120,6 @@ final void releaseChildren() { /// @return how many children are registered right now, for tests asserting that a closed child unregistered final int childCount() { - Set set = children; - return set == null ? 0 : set.size(); + return children.size(); } } From aa5781ae4843ae2c3a31e198880c67bcfd903e95 Mon Sep 17 00:00:00 2001 From: Davide Angelocola Date: Tue, 17 Nov 2026 08:00:46 +0100 Subject: [PATCH 3/5] Transaction.commit/rollback release their children even when RocksDB reports an error RocksDB clears the transaction before returning most commit/rollback errors, which invalidates its iterators and frees its snapshot; checkError throwing skipped the sweep and left them registered over a cleared batch. Co-Authored-By: Claude Sonnet 5 --- .../dfa1/rocksdbffm/NativeObjectParent.java | 3 +- .../github/dfa1/rocksdbffm/Transaction.java | 28 +++++++++++++------ 2 files changed, 22 insertions(+), 9 deletions(-) diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectParent.java b/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectParent.java index 9fa7ea3d..b7a3db90 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectParent.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectParent.java @@ -26,10 +26,11 @@ abstract class NativeObjectParent extends NativeObjectChild { /// A concurrent set, never behind a lock: [#unregisterChild(NativeObjectChild)] runs inside a child's own monitor /// while a sweep calls into the children, so a lock here would deadlock against them. - private final Set children = ConcurrentHashMap.newKeySet(); + private final Set children; protected NativeObjectParent(MemorySegment ptr) { super(ptr); + children = ConcurrentHashMap.newKeySet(); } /// Registers `child` to be closed automatically before this object's own native resource is diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/Transaction.java b/core/src/main/java/io/github/dfa1/rocksdbffm/Transaction.java index caf538e1..1c94192c 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/Transaction.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/Transaction.java @@ -843,26 +843,38 @@ public Snapshot getSnapshot() { // ----------------------------------------------------------------------- /// Commits all staged operations in this transaction. Iterators and the [#getSnapshot() snapshot] obtained - /// from this transaction are closed: RocksDB invalidates the iterators and frees the snapshot on commit. + /// from this transaction are closed, whether or not the commit succeeds: RocksDB invalidates the iterators and + /// frees the snapshot. public void commit() { try (Arena arena = Arena.ofConfined()) { MemorySegment err = NativeCalls.errHolder(arena); - MH_COMMIT.invokeExact(ptr(), err); - NativeCalls.checkError(err); - releaseChildren(); + try { + MH_COMMIT.invokeExact(ptr(), err); + NativeCalls.checkError(err); + } finally { + // Also on failure: RocksDB clears the transaction before reporting most errors, which invalidates + // the iterators and frees the snapshot, so they must not stay usable here. + releaseChildren(); + } } catch (Throwable t) { throw NativeCalls.wrapInvokeFailure("transaction commit failed", t); } } /// Rolls back all staged operations in this transaction. Iterators and the [#getSnapshot() snapshot] obtained - /// from this transaction are closed: RocksDB invalidates the iterators and frees the snapshot on rollback. + /// from this transaction are closed, whether or not the rollback succeeds: RocksDB invalidates the iterators and + /// frees the snapshot. public void rollback() { try (Arena arena = Arena.ofConfined()) { MemorySegment err = NativeCalls.errHolder(arena); - MH_ROLLBACK.invokeExact(ptr(), err); - NativeCalls.checkError(err); - releaseChildren(); + try { + MH_ROLLBACK.invokeExact(ptr(), err); + NativeCalls.checkError(err); + } finally { + // Also on failure: RocksDB clears the transaction before reporting most errors, which invalidates + // the iterators and frees the snapshot, so they must not stay usable here. + releaseChildren(); + } } catch (Throwable t) { throw NativeCalls.wrapInvokeFailure("transaction rollback failed", t); } From 7166c6df0cbd99e4db0a483863db53f5fd32880c Mon Sep 17 00:00:00 2001 From: Davide Angelocola Date: Tue, 17 Nov 2026 08:03:39 +0100 Subject: [PATCH 4/5] Transaction: finally at the end of commit/rollback, comment why rollbackToSavePoint has none Co-Authored-By: Claude Sonnet 5 --- .../github/dfa1/rocksdbffm/Transaction.java | 30 +++++++++---------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/Transaction.java b/core/src/main/java/io/github/dfa1/rocksdbffm/Transaction.java index 1c94192c..94324258 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/Transaction.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/Transaction.java @@ -848,16 +848,14 @@ public Snapshot getSnapshot() { public void commit() { try (Arena arena = Arena.ofConfined()) { MemorySegment err = NativeCalls.errHolder(arena); - try { - MH_COMMIT.invokeExact(ptr(), err); - NativeCalls.checkError(err); - } finally { - // Also on failure: RocksDB clears the transaction before reporting most errors, which invalidates - // the iterators and frees the snapshot, so they must not stay usable here. - releaseChildren(); - } + MH_COMMIT.invokeExact(ptr(), err); + NativeCalls.checkError(err); } catch (Throwable t) { throw NativeCalls.wrapInvokeFailure("transaction commit failed", t); + } finally { + // Also on failure: RocksDB clears the transaction before reporting most errors, which invalidates the + // iterators and frees the snapshot, so they must not stay usable here. + releaseChildren(); } } @@ -867,16 +865,14 @@ public void commit() { public void rollback() { try (Arena arena = Arena.ofConfined()) { MemorySegment err = NativeCalls.errHolder(arena); - try { - MH_ROLLBACK.invokeExact(ptr(), err); - NativeCalls.checkError(err); - } finally { - // Also on failure: RocksDB clears the transaction before reporting most errors, which invalidates - // the iterators and frees the snapshot, so they must not stay usable here. - releaseChildren(); - } + MH_ROLLBACK.invokeExact(ptr(), err); + NativeCalls.checkError(err); } catch (Throwable t) { throw NativeCalls.wrapInvokeFailure("transaction rollback failed", t); + } finally { + // Also on failure: RocksDB clears the transaction before reporting most errors, which invalidates the + // iterators and frees the snapshot, so they must not stay usable here. + releaseChildren(); } } @@ -896,6 +892,8 @@ public void rollbackToSavePoint() { MemorySegment err = NativeCalls.errHolder(arena); MH_ROLLBACK_TO_SAVEPOINT.invokeExact(ptr(), err); NativeCalls.checkError(err); + // Only after success, unlike commit/rollback: the one error here is NotFound (no savepoint), which + // leaves the write batch and so its iterators untouched, and they stay valid. releaseChildren(RocksIterator.class); } catch (Throwable t) { throw NativeCalls.wrapInvokeFailure("transaction rollbackToSavePoint failed", t); From 7f03a8792a9c41fcee4fbb374bc0ddff9f352168 Mon Sep 17 00:00:00 2001 From: Davide Angelocola Date: Wed, 18 Nov 2026 07:26:46 +0100 Subject: [PATCH 5/5] Tests: share fakePtr between NativeObjectTest and NativeObjectParentTest Closes #299 Co-Authored-By: Claude Sonnet 5 --- .../dfa1/rocksdbffm/NativeObjectParentTest.java | 5 +---- .../github/dfa1/rocksdbffm/NativeObjectTest.java | 5 +---- .../io/github/dfa1/rocksdbffm/TestPointers.java | 15 +++++++++++++++ 3 files changed, 17 insertions(+), 8 deletions(-) create mode 100644 core/src/test/java/io/github/dfa1/rocksdbffm/TestPointers.java diff --git a/core/src/test/java/io/github/dfa1/rocksdbffm/NativeObjectParentTest.java b/core/src/test/java/io/github/dfa1/rocksdbffm/NativeObjectParentTest.java index 5c933292..12870e6a 100644 --- a/core/src/test/java/io/github/dfa1/rocksdbffm/NativeObjectParentTest.java +++ b/core/src/test/java/io/github/dfa1/rocksdbffm/NativeObjectParentTest.java @@ -12,6 +12,7 @@ import java.util.concurrent.atomic.AtomicInteger; import java.util.stream.IntStream; +import static io.github.dfa1.rocksdbffm.TestPointers.fakePtr; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatCode; import static org.assertj.core.api.Assertions.assertThatThrownBy; @@ -50,10 +51,6 @@ protected void tryClose(MemorySegment ptr) { } } - private static MemorySegment fakePtr(long address) { - return MemorySegment.ofAddress(address); - } - @Test void registerChild_beforeParentCloses_isClosedByParentSweep() { // Given diff --git a/core/src/test/java/io/github/dfa1/rocksdbffm/NativeObjectTest.java b/core/src/test/java/io/github/dfa1/rocksdbffm/NativeObjectTest.java index bfdc1657..b2eb3012 100644 --- a/core/src/test/java/io/github/dfa1/rocksdbffm/NativeObjectTest.java +++ b/core/src/test/java/io/github/dfa1/rocksdbffm/NativeObjectTest.java @@ -11,6 +11,7 @@ import java.util.concurrent.atomic.AtomicInteger; import java.util.stream.IntStream; +import static io.github.dfa1.rocksdbffm.TestPointers.fakePtr; import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThatThrownBy; import static org.assertj.core.api.Assertions.catchThrowable; @@ -40,10 +41,6 @@ protected void tryClose(MemorySegment ptr) { } } - private static MemorySegment fakePtr(long address) { - return MemorySegment.ofAddress(address); - } - @Test void ptr_returnsTheConstructedPointer() { // Given diff --git a/core/src/test/java/io/github/dfa1/rocksdbffm/TestPointers.java b/core/src/test/java/io/github/dfa1/rocksdbffm/TestPointers.java new file mode 100644 index 00000000..a87b9849 --- /dev/null +++ b/core/src/test/java/io/github/dfa1/rocksdbffm/TestPointers.java @@ -0,0 +1,15 @@ +package io.github.dfa1.rocksdbffm; + +import java.lang.foreign.MemorySegment; + +/// Native-pointer helpers shared across tests. +final class TestPointers { + + private TestPointers() { + } + + /// A pointer that is never dereferenced, for tests that only exercise a wrapper's lifecycle. + static MemorySegment fakePtr(long address) { + return MemorySegment.ofAddress(address); + } +}