From 944e5c933c59be7e619c87c884bd3643b546c2dc Mon Sep 17 00:00:00 2001 From: Davide Angelocola Date: Wed, 18 Nov 2026 08:35:22 +0100 Subject: [PATCH] Policy: every non-static field is initialized in the constructor AGENTS.md and CONTRIBUTING.md state the rule; the remaining inline field initializers in core, tools, tests and the JMH benchmarks move into constructors. Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 1 + CONTRIBUTING.md | 1 + .../benchmark/FfmValueSizeBenchmark.java | 21 ++++++----- .../benchmark/MultiGetScaleBenchmark.java | 15 +++++--- .../benchmark/TryCatchWrapperBenchmark.java | 12 +++++-- .../dfa1/rocksdbffm/JfrEventNotifier.java | 9 +++-- .../io/github/dfa1/rocksdbffm/LiveFiles.java | 2 +- .../dfa1/rocksdbffm/LiveFilesStorageInfo.java | 2 +- .../io/github/dfa1/rocksdbffm/NativeDB.java | 4 +-- .../github/dfa1/rocksdbffm/NativeObject.java | 3 +- .../dfa1/rocksdbffm/NativeObjectChild.java | 3 +- .../github/dfa1/rocksdbffm/PerfContext.java | 3 +- .../dfa1/rocksdbffm/PlainTableOptions.java | 24 ++++++++----- .../github/dfa1/rocksdbffm/ReadOptions.java | 3 +- .../github/dfa1/rocksdbffm/RocksIterator.java | 3 +- .../dfa1/rocksdbffm/UpcallRegistry.java | 9 +++-- .../CloseFromAnotherThreadTest.java | 36 +++++++++++-------- .../dfa1/rocksdbffm/sstdump/SstDumpTool.java | 3 +- 18 files changed, 100 insertions(+), 54 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c1d1c4b9..8786d1c1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a4af89e0..550ebcdc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 diff --git a/benchmarks/src/test/java/io/github/dfa1/rocksdbffm/benchmark/FfmValueSizeBenchmark.java b/benchmarks/src/test/java/io/github/dfa1/rocksdbffm/benchmark/FfmValueSizeBenchmark.java index 3bed5646..64887e72 100644 --- a/benchmarks/src/test/java/io/github/dfa1/rocksdbffm/benchmark/FfmValueSizeBenchmark.java +++ b/benchmarks/src/test/java/io/github/dfa1/rocksdbffm/benchmark/FfmValueSizeBenchmark.java @@ -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 sizeMapper = value -> { - sizeSink += value.byteSize(); - return Boolean.TRUE; - }; - private final Mapper copyMapper = value -> { - MemorySegment.copy(value, 0, valueMemorySegment, 0, value.byteSize()); - return Boolean.TRUE; - }; + private final Mapper sizeMapper; + private final Mapper 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 { diff --git a/benchmarks/src/test/java/io/github/dfa1/rocksdbffm/benchmark/MultiGetScaleBenchmark.java b/benchmarks/src/test/java/io/github/dfa1/rocksdbffm/benchmark/MultiGetScaleBenchmark.java index 4730a064..6c306679 100644 --- a/benchmarks/src/test/java/io/github/dfa1/rocksdbffm/benchmark/MultiGetScaleBenchmark.java +++ b/benchmarks/src/test/java/io/github/dfa1/rocksdbffm/benchmark/MultiGetScaleBenchmark.java @@ -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 zeroCopyMapper = value -> { - zeroCopyAccumulator[0] += value.byteSize(); - return Boolean.TRUE; - }; + private final long[] zeroCopyAccumulator; + private final Mapper 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 { diff --git a/benchmarks/src/test/java/io/github/dfa1/rocksdbffm/benchmark/TryCatchWrapperBenchmark.java b/benchmarks/src/test/java/io/github/dfa1/rocksdbffm/benchmark/TryCatchWrapperBenchmark.java index afda9f3c..96fee9a5 100644 --- a/benchmarks/src/test/java/io/github/dfa1/rocksdbffm/benchmark/TryCatchWrapperBenchmark.java +++ b/benchmarks/src/test/java/io/github/dfa1/rocksdbffm/benchmark/TryCatchWrapperBenchmark.java @@ -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 { diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/JfrEventNotifier.java b/core/src/main/java/io/github/dfa1/rocksdbffm/JfrEventNotifier.java index 4e050d19..27bc0486 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/JfrEventNotifier.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/JfrEventNotifier.java @@ -52,12 +52,15 @@ public final class JfrEventNotifier implements EventNotifier { private final SstFileManager sstFileManager; - private final Map flushes = new ConcurrentHashMap<>(); - private final Map compactions = new ConcurrentHashMap<>(); - private final Map stalls = new ConcurrentHashMap<>(); + private final Map flushes; + private final Map compactions; + private final Map stalls; private JfrEventNotifier(SstFileManager sstFileManager) { this.sstFileManager = sstFileManager; + this.flushes = new ConcurrentHashMap<>(); + this.compactions = new ConcurrentHashMap<>(); + this.stalls = new ConcurrentHashMap<>(); } static { diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/LiveFiles.java b/core/src/main/java/io/github/dfa1/rocksdbffm/LiveFiles.java index b5faf9c6..2ab730e2 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/LiveFiles.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/LiveFiles.java @@ -103,7 +103,7 @@ public LiveFileInfo get(int index) { @Override public Iterator iterator() { return new Iterator<>() { - private int i = 0; + private int i; @Override public boolean hasNext() { diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/LiveFilesStorageInfo.java b/core/src/main/java/io/github/dfa1/rocksdbffm/LiveFilesStorageInfo.java index f12d79d9..2d00d794 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/LiveFilesStorageInfo.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/LiveFilesStorageInfo.java @@ -94,7 +94,7 @@ public LiveFileStorageInfo get(int index) { @Override public Iterator iterator() { return new Iterator<>() { - private int i = 0; + private int i; @Override public boolean hasNext() { 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 2ccf935f..935cb126 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/NativeDB.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/NativeDB.java @@ -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> columnFamilies = - new AtomicReference<>(Collections.unmodifiableSequencedMap(new LinkedHashMap<>())); + private final AtomicReference> 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 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 1e07d236..f11e6f4c 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObject.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObject.java @@ -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. 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 1e3406d5..d091214e 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectChild.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/NativeObjectChild.java @@ -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 diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/PerfContext.java b/core/src/main/java/io/github/dfa1/rocksdbffm/PerfContext.java index fa3f416f..d16a3088 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/PerfContext.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/PerfContext.java @@ -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. diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/PlainTableOptions.java b/core/src/main/java/io/github/dfa1/rocksdbffm/PlainTableOptions.java index 92cb72d8..e8732f49 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/PlainTableOptions.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/PlainTableOptions.java @@ -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. 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 35e1eaaf..a2617472 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/ReadOptions.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/ReadOptions.java @@ -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 = new AtomicReference<>(); + private final AtomicReference snapshot; private ReadOptions(MemorySegment ptr) { super(ptr); + this.snapshot = new AtomicReference<>(); this.boundsArena = Arena.ofAuto(); } diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/RocksIterator.java b/core/src/main/java/io/github/dfa1/rocksdbffm/RocksIterator.java index ad7baff0..796e398b 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/RocksIterator.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/RocksIterator.java @@ -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); diff --git a/core/src/main/java/io/github/dfa1/rocksdbffm/UpcallRegistry.java b/core/src/main/java/io/github/dfa1/rocksdbffm/UpcallRegistry.java index 0e318928..5a072be5 100644 --- a/core/src/main/java/io/github/dfa1/rocksdbffm/UpcallRegistry.java +++ b/core/src/main/java/io/github/dfa1/rocksdbffm/UpcallRegistry.java @@ -15,8 +15,13 @@ /// @param the type of value being registered (a callback, or a bundle of callback state) final class UpcallRegistry { - private final ConcurrentHashMap registry = new ConcurrentHashMap<>(); - private final AtomicLong nextId = new AtomicLong(1); + private final ConcurrentHashMap 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. /// diff --git a/core/src/test/java/io/github/dfa1/rocksdbffm/CloseFromAnotherThreadTest.java b/core/src/test/java/io/github/dfa1/rocksdbffm/CloseFromAnotherThreadTest.java index 920aa9e8..5d862791 100644 --- a/core/src/test/java/io/github/dfa1/rocksdbffm/CloseFromAnotherThreadTest.java +++ b/core/src/test/java/io/github/dfa1/rocksdbffm/CloseFromAnotherThreadTest.java @@ -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 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 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() { diff --git a/tools/sst-dump/src/main/java/io/github/dfa1/rocksdbffm/sstdump/SstDumpTool.java b/tools/sst-dump/src/main/java/io/github/dfa1/rocksdbffm/sstdump/SstDumpTool.java index 694276c3..b0864865 100644 --- a/tools/sst-dump/src/main/java/io/github/dfa1/rocksdbffm/sstdump/SstDumpTool.java +++ b/tools/sst-dump/src/main/java/io/github/dfa1/rocksdbffm/sstdump/SstDumpTool.java @@ -58,10 +58,11 @@ public static final class Request { private boolean verifyChecksum; private boolean showProperties; private Integer readNum; - private final List extraArgs = new ArrayList<>(); + private final List extraArgs; private Request(Path target) { this.target = target; + this.extraArgs = new ArrayList<>(); } /// Sets which `sst_dump` command to run.