You own a class wrapping an off-heap buffer. How do you design its resource cleanup using AutoCloseable and a Cleaner backstop, and what are the pitfalls?

## The scenario You have a class that owns an **off-heap buffer** — memory allocated outside the Java heap (e.g. via `Unsafe`, a native `malloc`, or a direct `ByteBuffer`). The GC does **not** track off-heap bytes, so if your wrapper object is collected without freeing that memory, you leak native memory that can crash the process under load. You need a robust release strategy. ## Layer 1 (primary): deterministic release via AutoCloseable The **correct primary** mechanism is **explicit, deterministic** cleanup. Implement `AutoCloseable` and free in `close()`, and document try-with-resources: ```java try (OffHeapBuffer buf = new OffHeapBuffer(1 << 20)) { buf.put(...); } // close() runs here, deterministically, regardless of exceptions ``` This releases memory **at a known point**, independent of GC behavior. Never make correctness depend on GC timing. ## Layer 2 (backstop): Cleaner for forgotten closes Humans forget `close()`. A `Cleaner` is the **safety net**: if the wrapper becomes unreachable without `close()`, the Cleaner eventually frees the buffer. Design: ```java public final class OffHeapBuffer implements AutoCloseable { private static final Cleaner CLEANER = Cleaner.create(); // Separate state: holds ONLY the raw handle, never OffHeapBuffer. private static final class State implements Runnable { private long address; // 0 == freed State(long address) { this.address = address; } @Override public synchronized void run() { if (address != 0) { freeNative(address); address = 0; } } } private final State state; private final Cleaner.Cleanable cleanable; public OffHeapBuffer(long size) { this.state = new State(allocNative(size)); this.cleanable = CLEANER.register(this, state); } @Override public void close() { cleanable.clean(); } // prompt + idempotent private static native long allocNative(long size); private static native void freeNative(long address); } ``` `Cleanable.clean()` runs the action **at most once**: whichever of `close()` or the GC-triggered path happens first wins, so the buffer is never double-freed. ## Pitfall 1: capturing the wrapper (the cardinal sin) The cleanup `State` **must not** reference the `OffHeapBuffer` instance — not directly, and not via a **lambda or non-static inner class**, which capture the enclosing instance implicitly. If it did, the Cleaner's internal phantom reference would keep the wrapper reachable, so it would **never** become phantom-reachable, the backstop would **never** fire, and you'd leak. Hence `State` is a **static** nested class holding only the `long address`. ## Pitfall 2: double-free / use-after-free Guard the handle: store `0` after freeing and check before freeing (`if (address != 0)`). This makes `run()` idempotent at the resource level too, surviving any path that triggers cleanup twice. ## Pitfall 3: races between close() and the cleaner thread `close()` runs on the caller's thread; the GC-triggered cleanup runs on the **Cleaner's daemon thread**. If both can occur, synchronize the `run()` (as above) so freeing is atomic. Also beware **use-after-close**: methods must not touch the buffer after `close()` (check `address == 0` and throw `IllegalStateException`). ## Pitfall 4: assuming Cleaner is timely The Cleaner fires **whenever the GC decides** the object is phantom-reachable — possibly long after the last use, possibly only under memory pressure (which off-heap allocations don't even create!). So **off-heap exhaustion can occur even though heap is fine**, because the GC sees no pressure to collect the small wrapper. This is exactly why the AutoCloseable path must be primary. ## Pitfall 5: reachability of the wrapper during a long method Subtle JIT issue: if a long-running instance method only reads the off-heap handle early, the GC may consider `this` unreachable mid-method and the Cleaner could free the buffer **while the method is still running**. Use `Reference.reachabilityFence(this)` at the end of such methods to keep `this` alive until the work completes. ## Modern alternative: Foreign Function & Memory API For new code targeting recent JDKs, the **Foreign Function & Memory (FFM) API** offers `Arena` / `MemorySegment` with **scoped, deterministic** native-memory management and bounds checking — often a cleaner fit than hand-rolled Cleaner plumbing. Evaluate it before reaching for Unsafe + Cleaner. ## Key takeaways - AutoCloseable + try-with-resources is the **primary**, deterministic path; Cleaner is the **backstop**. - State object must be static and never reference the wrapper. - Make freeing idempotent (`clean()` + guarded address) and thread-safe. - Cleaner timing is non-deterministic; off-heap leaks can outpace the GC. - Consider `reachabilityFence` for long methods, and FFM `Arena` for new designs.