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.