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
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -247,6 +247,7 @@ type (`ReadWriteDB`, `TtlDB`, …) or its capability interface, not on `RocksDB`

- American English everywhere (javadoc, comments, identifiers): recognize/optimize/finalize/serialize/normalize/behavior/color — never -ise/-isation/-our. Matches the JDK (Object.finalize, Serializable).
- code is indented with tabs (enforced by checkstyle)
- every non-static field is initialized in the constructor (`this.x = ...`), never at its declaration or in an instance initializer block: an object's whole state, and the order it is built in, reads in one place, and a constructor that must call something last (`childOf(...)`) can see that every field is already assigned. `static final` constants are unaffected. A field with no meaningful value yet is left unassigned, not given a placeholder
- always keep the MethodHandles private static final
- never pass a `MethodHandle` as a method parameter, even internally: `invokeExact` on a `static final` field lets the JIT treat the target as a compile-time constant; routed through a parameter, that constant-folding is lost. Each call site must invoke its own `MH_` field directly, even if that means near-duplicate call sites instead of one shared helper
- **Documented exception:** any class with the same cold-path, no-arg-getter/single-primitive-setter shape — every `*Options` class, plus [StatisticsHistogramData], [SstFileManager], [Env], [Cache], [Replayer], [ColumnFamilyHandle], [Snapshot], [WriteBufferManager], and the read-only event-listener payload views ([CompactionJobInfo], [FlushJobInfo], [MemTableInfo], [ExternalFileIngestionInfo]) that have at least one plain-shape field — routes through the static helpers on `NativeFields` instead of inlining its own `try { mh.invokeExact(...) } catch (Throwable t) { ... }` at every call site: `NativeFields.getInt(mh, ptr())`, `NativeFields.setInt(mh, ptr(), value)`, and the same pattern for `getLong`/`setLong`, `getDouble`/`setDouble`, `getBoolean`/`setBoolean`, `getMemorySize`/`setMemorySize`. The payload views hold a raw `MemorySegment ptr` field rather than extending `NativeObject`, which is fine: `NativeFields`'s helpers take `ptr` as a plain parameter, so nothing about them requires a `NativeObject` receiver. No per-instance delegate object either — `NativeFields` is stateless shared FFM plumbing, the same shape as `NativeCalls.errHolder`/`checkError`/`wrapInvokeFailure` are already static on `NativeCalls`. These are cold-path calls — made once (or once per read/write call in `ReadOptions`/`WriteOptions`, still nowhere near `Get`/`Put`/iterator internals) — so the JIT constant-folding the base rule protects is immaterial here, and consolidating the near-identical `catch (Throwable t)` blocks meaningfully shrinks the permanently-unreachable defensive code cataloged in ADR 0004. Scope stays tight: only a plain no-arg getter or a setter taking `ptr()` plus exactly one primitive qualifies. A pure, always-succeeding value transform in the argument expression is still in scope — e.g. `NativeCalls.toByte(value)`, a null-to-sentinel ternary (`x == null ? -1L : x.toBytes()`), or a bitmask encode/decode (`TraceFilter.toMask(filters)`) — since none of those can throw, so there is no risk of a validation failure being misattributed to `NativeCalls.wrapInvokeFailure`'s "native setter failed" message. What stays a raw, per-call-site `MethodHandle` invocation is a pointer-argument call, a multi-arg call, or a value expression that can itself throw (e.g. `TransactionDBOptions`'s `toMillisOrNoTimeout`, which rejects a negative `Duration`) or that maps onto more than a direct value substitution (e.g. a boolean mapped onto a non-0/1 native enum). Do not route a hot-path class (`WriteBatch`, `Transaction(DB)`, `RocksIterator`, `SstFileWriter`, `PinnableSlice`/`PinnableHandle`, `WalIterator`, ...) through `NativeFields` without the same justification
Expand Down
1 change: 1 addition & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ Cloned without `--recurse-submodules`? Run `git submodule update --init --recurs
## Making a change

- Code is indented with **tabs** (enforced by checkstyle); American English everywhere.
- Every non-static field is initialized in the constructor, not at its declaration (`static final` constants excepted).
- Every class wrapping a native pointer extends `NativeObject`; no public constructors, use static
factories. See [docs/explanation.md#lifecycle-and-ownership](docs/explanation.md#lifecycle-and-ownership).
- Only the C API (`rocksdb/c.h`) is bound. A missing wrapper is a Type A gap, a missing C function a
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -125,14 +125,19 @@ public class FfmValueSizeBenchmark {
// call (a fresh capturing lambda or an autoboxed Long would); same idea as
// MultiGetScaleBenchmark's zeroCopyMapper.
private long sizeSink;
private final Mapper<Boolean> sizeMapper = value -> {
sizeSink += value.byteSize();
return Boolean.TRUE;
};
private final Mapper<Boolean> copyMapper = value -> {
MemorySegment.copy(value, 0, valueMemorySegment, 0, value.byteSize());
return Boolean.TRUE;
};
private final Mapper<Boolean> sizeMapper;
private final Mapper<Boolean> copyMapper;

public FfmValueSizeBenchmark() {
this.sizeMapper = value -> {
sizeSink += value.byteSize();
return Boolean.TRUE;
};
this.copyMapper = value -> {
MemorySegment.copy(value, 0, valueMemorySegment, 0, value.byteSize());
return Boolean.TRUE;
};
}

@Setup(Level.Trial)
public void setup() throws Exception {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -83,11 +83,16 @@ public class MultiGetScaleBenchmark {
// Mapper -- like CopyResult.Copied.INSTANCE on the ByteBuffer tier -- returns a shared
// constant instead of autoboxing a fresh Long per key; otherwise the two tiers wouldn't
// be allocation-comparable.
private final long[] zeroCopyAccumulator = new long[1];
private final Mapper<Boolean> zeroCopyMapper = value -> {
zeroCopyAccumulator[0] += value.byteSize();
return Boolean.TRUE;
};
private final long[] zeroCopyAccumulator;
private final Mapper<Boolean> zeroCopyMapper;

public MultiGetScaleBenchmark() {
this.zeroCopyAccumulator = new long[1];
this.zeroCopyMapper = value -> {
zeroCopyAccumulator[0] += value.byteSize();
return Boolean.TRUE;
};
}

@Setup(Level.Trial)
public void setup() throws Exception {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -60,9 +60,15 @@ public class TryCatchWrapperBenchmark {

// Same values as A/B/LEN, but as instance fields: the JIT cannot treat them as
// constants, so a lambda reading them must capture them.
private MemorySegment a = A;
private MemorySegment b = B;
private long len = LEN;
private MemorySegment a;
private MemorySegment b;
private long len;

public TryCatchWrapperBenchmark() {
this.a = A;
this.b = B;
this.len = LEN;
}

@FunctionalInterface
private interface ThrowingIntCall {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -52,12 +52,15 @@
public final class JfrEventNotifier implements EventNotifier {

private final SstFileManager sstFileManager;
private final Map<FlushSlot, PendingFlush> flushes = new ConcurrentHashMap<>();
private final Map<Long, PendingCompaction> compactions = new ConcurrentHashMap<>();
private final Map<ColumnFamilyName, OpenStall> stalls = new ConcurrentHashMap<>();
private final Map<FlushSlot, PendingFlush> flushes;
private final Map<Long, PendingCompaction> compactions;
private final Map<ColumnFamilyName, OpenStall> stalls;

private JfrEventNotifier(SstFileManager sstFileManager) {
this.sstFileManager = sstFileManager;
this.flushes = new ConcurrentHashMap<>();
this.compactions = new ConcurrentHashMap<>();
this.stalls = new ConcurrentHashMap<>();
}

static {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ public LiveFileInfo get(int index) {
@Override
public Iterator<LiveFileInfo> iterator() {
return new Iterator<>() {
private int i = 0;
private int i;

@Override
public boolean hasNext() {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ public LiveFileStorageInfo get(int index) {
@Override
public Iterator<LiveFileStorageInfo> iterator() {
return new Iterator<>() {
private int i = 0;
private int i;

@Override
public boolean hasNext() {
Expand Down
4 changes: 2 additions & 2 deletions core/src/main/java/io/github/dfa1/rocksdbffm/NativeDB.java
Original file line number Diff line number Diff line change
Expand Up @@ -32,11 +32,11 @@ abstract class NativeDB extends NativeObjectParent {

/// In open order, then creation order. An immutable snapshot replaced wholesale on every change
/// (copy-on-write): lookups are lock-free, and changes happen only on open, create and drop.
private final AtomicReference<SequencedMap<ColumnFamilyName, ColumnFamilyHandle>> columnFamilies =
new AtomicReference<>(Collections.unmodifiableSequencedMap(new LinkedHashMap<>()));
private final AtomicReference<SequencedMap<ColumnFamilyName, ColumnFamilyHandle>> columnFamilies;

protected NativeDB(MemorySegment ptr) {
super(ptr);
this.columnFamilies = new AtomicReference<>(Collections.unmodifiableSequencedMap(new LinkedHashMap<>()));
}

/// The classes whose frames run a caller-supplied callback while RocksDB, or a pinned value, still uses the
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,13 +27,14 @@ public abstract class NativeObject implements AutoCloseable {

/// Set by [#makeImmortal()] and never cleared. Usually set before the object is published (a `DEFAULTS` field),
/// but a [CompactionFilter] sets it on every attach, hence atomic.
private final AtomicBoolean immortal = new AtomicBoolean();
private final AtomicBoolean immortal;

/// Initializes this wrapper with the given native pointer.
///
/// @param owningPointer the non-NULL native pointer this object now owns
protected NativeObject(MemorySegment owningPointer) {
this.owningPointer = new AtomicReference<>(owningPointer);
this.immortal = new AtomicBoolean();
}

/// Returns the current native pointer.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,11 @@ abstract class NativeObjectChild extends NativeObject {

/// Private monitor: `synchronized (this)` would let user code that locks a wrapper it holds block, or deadlock
/// with, a parent's close.
private final Object lock = new Object();
private final Object lock;

protected NativeObjectChild(MemorySegment owningPointer) {
super(owningPointer);
this.lock = new Object();
}

/// Declares that this object borrows native memory from `parent`: it is registered as its child, so the parent's close releases it first, and
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -77,10 +77,11 @@ public final class PerfContext extends NativeObject {
);

/// The thread whose perf context this wraps; the native object is a view of that thread's `thread_local`.
private final Thread owner = Thread.currentThread();
private final Thread owner;

private PerfContext(MemorySegment ptr) {
super(ptr);
this.owner = Thread.currentThread();
}

/// Returns [#ptr()] for a call that reads or resets the counters.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -47,16 +47,24 @@ int getValue() {
/// Sentinel for [#setUserKeyLength]: keys have variable length (the default).
public static final int VARIABLE_LENGTH = 0;

private int userKeyLength = VARIABLE_LENGTH;
private int bloomBitsPerKey = 10;
private double hashTableRatio = 0.75;
private long indexSparseness = 16;
private long hugePageTlbSize = 0;
private EncodingType encodingType = EncodingType.PLAIN;
private boolean fullScanMode = false;
private boolean storeIndexInFile = false;
private int userKeyLength;
private int bloomBitsPerKey;
private double hashTableRatio;
private long indexSparseness;
private long hugePageTlbSize;
private EncodingType encodingType;
private boolean fullScanMode;
private boolean storeIndexInFile;

private PlainTableOptions() {
this.userKeyLength = VARIABLE_LENGTH;
this.bloomBitsPerKey = 10;
this.hashTableRatio = 0.75;
this.indexSparseness = 16;
this.hugePageTlbSize = 0;
this.encodingType = EncodingType.PLAIN;
this.fullScanMode = false;
this.storeIndexInFile = false;
}

/// Creates [PlainTableOptions] with RocksDB defaults.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -125,10 +125,11 @@ public final class ReadOptions extends NativeObjectParent {

/// The snapshot installed by [#setSnapshot(Snapshot)], which the native struct holds a raw pointer to. Reads
/// through [#readPtr()] throw once it is closed, instead of dereferencing the freed snapshot.
private final AtomicReference<Snapshot> snapshot = new AtomicReference<>();
private final AtomicReference<Snapshot> snapshot;

private ReadOptions(MemorySegment ptr) {
super(ptr);
this.snapshot = new AtomicReference<>();
this.boundsArena = Arena.ofAuto();
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -89,11 +89,12 @@ public final class RocksIterator extends NativeObjectChild {

// The key/value length out-param, reused across calls. On the heap (a long[] is size_t-aligned), so there is no
// native memory to free, from whichever thread a parent's close releases this iterator.
private final MemorySegment lenSegment = MemorySegment.ofArray(new long[1]);
private final MemorySegment lenSegment;

/// Package-private: created via [#create].
private RocksIterator(NativeObjectParent owningDb, ReadOptions readOptions, MemorySegment ptr) {
super(ptr);
this.lenSegment = MemorySegment.ofArray(new long[1]);
// Two parents: the database or transaction, and the options, whose iterate bounds the native iterator keeps raw
// pointers into. Holding them also keeps the options' bounds memory reachable.
childOf(owningDb, readOptions);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,13 @@
/// @param <T> the type of value being registered (a callback, or a bundle of callback state)
final class UpcallRegistry<T> {

private final ConcurrentHashMap<Long, T> registry = new ConcurrentHashMap<>();
private final AtomicLong nextId = new AtomicLong(1);
private final ConcurrentHashMap<Long, T> registry;
private final AtomicLong nextId;

UpcallRegistry() {
this.registry = new ConcurrentHashMap<>();
this.nextId = new AtomicLong(1);
}

/// Registers `value` and returns the `state` pointer to pass to the native call.
///
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,24 +20,30 @@
/// fails, so a confined arena closed from the wrong thread shows up only as an ERROR log line and a leak.
class CloseFromAnotherThreadTest {

private final List<LogRecord> errors = new CopyOnWriteArrayList<>();
private final Logger logger = Logger.getLogger(NativeObject.class.getName());
private final Handler handler = new Handler() {
@Override
public void publish(LogRecord record) {
if (record.getLevel().intValue() >= Level.SEVERE.intValue()) {
errors.add(record);
private final List<LogRecord> errors;
private final Logger logger;
private final Handler handler;

CloseFromAnotherThreadTest() {
this.errors = new CopyOnWriteArrayList<>();
this.logger = Logger.getLogger(NativeObject.class.getName());
this.handler = new Handler() {
@Override
public void publish(LogRecord record) {
if (record.getLevel().intValue() >= Level.SEVERE.intValue()) {
errors.add(record);
}
}
}

@Override
public void flush() {
}
@Override
public void flush() {
}

@Override
public void close() {
}
};
@Override
public void close() {
}
};
}

@BeforeEach
void captureErrors() {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -58,10 +58,11 @@ public static final class Request {
private boolean verifyChecksum;
private boolean showProperties;
private Integer readNum;
private final List<String> extraArgs = new ArrayList<>();
private final List<String> extraArgs;

private Request(Path target) {
this.target = target;
this.extraArgs = new ArrayList<>();
}

/// Sets which `sst_dump` command to run.
Expand Down
Loading