Skip to content
Merged
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);
}
}
}
}
}
104 changes: 29 additions & 75 deletions core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectParent.java
Original file line number Diff line number Diff line change
@@ -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;

Expand All @@ -11,41 +9,28 @@
/// 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
/// 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<NativeObjectChild> 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<NativeObjectChild> children;

protected NativeObjectParent(MemorySegment ptr) {
super(ptr);
children = ConcurrentHashMap.newKeySet();
}

/// Registers `child` to be closed automatically before this object's own native resource is
Expand Down Expand Up @@ -77,31 +62,24 @@ 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.
///
/// 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) {
if (isImmortal()) {
// Never swept, so tracking the child would only pin it for the life of the JVM.
return;
}
Set<NativeObjectChild> set = children;
if (set == null) {
Set<NativeObjectChild> fresh = ConcurrentHashMap.newKeySet();
@SuppressWarnings("unchecked")
Set<NativeObjectChild> witness = (Set<NativeObjectChild>) 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();
}
}
Expand All @@ -113,60 +91,36 @@ final void registerChild(NativeObjectChild child) {
///
/// @param child the child resource to stop tracking
final void unregisterChild(NativeObjectChild child) {
Set<NativeObjectChild> 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.
///
/// A parent's [#tryClose(MemorySegment)] calls [#releaseChildren()] first. `release()` is safe on a child whether
/// 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<? extends NativeObjectChild> type) {
Set<NativeObjectChild> set = children;
if (set == null) {
return;
}
for (NativeObjectChild child : set) {
for (NativeObjectChild child : children) {
if (type.isInstance(child)) {
child.release();
}
}
}

/// @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();
/// 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);
}

@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);
/// @return how many children are registered right now, for tests asserting that a closed child unregistered
final int childCount() {
return children.size();
}

/// 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;
}
Loading
Loading