Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion core/src/main/java/io/github/dfa1/rocksdbffm/EnvOptions.java
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}
}
3 changes: 2 additions & 1 deletion core/src/main/java/io/github/dfa1/rocksdbffm/NativeDB.java
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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;
}
31 changes: 13 additions & 18 deletions core/src/main/java/io/github/dfa1/rocksdbffm/NativeObject.java
Original file line number Diff line number Diff line change
Expand Up @@ -71,29 +71,30 @@ 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
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 {
Expand All @@ -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
Expand Down
49 changes: 20 additions & 29 deletions core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectChild.java
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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);
}
}
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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<? extends NativeObjectChild> type) {
Set<NativeObjectChild> set = children;
if (set == null) {
Expand All @@ -136,37 +141,15 @@ final void releaseChildren(Class<? extends NativeObjectChild> 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<NativeObjectChild> 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<NativeObjectChild> 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;
}
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}
}
7 changes: 4 additions & 3 deletions core/src/main/java/io/github/dfa1/rocksdbffm/Transaction.java
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}
Expand All @@ -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);
}
Expand Down Expand Up @@ -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);
}

Expand Down
13 changes: 7 additions & 6 deletions core/src/main/java/io/github/dfa1/rocksdbffm/TransactionDB.java
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}

Expand Down
Loading
Loading