Why does the FFM API supersede JNI and sun.misc.Unsafe, and what trade-offs and risks should you weigh before adopting it?

## Background: three ways to leave the Java world Historically Java had three escape hatches, each flawed: 1. **JNI (Java Native Interface)** — the official native-call mechanism since Java 1.1. You declare a `native` method in Java, then write a matching **C function** using the **JNIEnv** interface to convert between Java and C types, compile it into a shared library *for every target platform*, and load it. It works, but: lots of boilerplate, easy to crash the JVM (bad pointer, wrong type), manual handling of object references, and a non-trivial per-call overhead at the boundary. 2. **`sun.misc.Unsafe`** — an *internal* JDK class (never a public API) that exposes raw memory operations. Widely (mis)used for off-heap memory and tricks, but it has **no bounds checking and no lifetime checking** — a wrong offset or freed pointer silently corrupts memory or crashes the process. The JDK has long wanted to **remove** it. 3. **Direct `ByteBuffer`** — public off-heap buffers, but limited (~2GB size cap, no deterministic free, awkward typed access). ## What FFM changes The **Foreign Function & Memory API** (`java.lang.foreign`, final in **Java 22**) unifies and fixes these: - **vs JNI:** the entire binding is **pure Java** — `Linker.nativeLinker()`, a `FunctionDescriptor`, and a `MethodHandle`. *No handwritten C glue, no separate C compiler step.* Performance is competitive with, and often better than, JNI because the boundary transition is leaner. - **vs Unsafe:** FFM provides the same off-heap power but **safely** — **spatial safety** (every `MemorySegment` is bounds-checked) and **temporal safety** (an `Arena` invalidates segments on close, so use-after-free throws an exception instead of crashing). And it's a **supported public API**, so the JDK can finally retire `Unsafe`. - **vs ByteBuffer:** no 2GB cap, deterministic lifetimes via arenas, and typed structured access via `MemoryLayout`/`VarHandle`. ## The trade-offs and risks a principal must weigh Adopting FFM is usually right for new native interop, but it is not free: 1. **JDK version floor.** It's *final* only from **Java 22**; on 17–21 it existed as a **preview** requiring `--enable-preview` (and the API shifted between previews). If you must run an older LTS, FFM may be unavailable or unstable. 2. **"Restricted" methods + native-access control.** Native calls and library lookups are **restricted operations** (they can break JVM integrity). The JVM emits warnings unless you explicitly grant native access to the module with **`--enable-native-access=<module>`** (or `ALL-UNNAMED`). This is intentional friction so native power is opt-in and auditable, but it's operational overhead you must plan for in deployment. 3. **Safety is *memory* safety, not *correctness*.** FFM stops Java-side out-of-bounds and use-after-free. It does **not** make the native side safe: a wrong `FunctionDescriptor` (mismatched ABI types), passing a too-small buffer, or the C code itself misbehaving can still crash the process. You're still calling into unmanaged code. 4. **Boundary cost remains.** Crossing into native code is still more expensive than a plain Java call; chatty fine-grained native calls can dominate runtime. Batch where possible, and consider `Linker.Option.isTrivial()` only for genuinely short, non-blocking calls (misusing it can stall the JVM, e.g. blocking GC). 5. **Lifetime discipline scales poorly if ad hoc.** Arenas make lifetimes explicit, but in large systems you must *design* ownership (who closes the arena, upcall-stub validity, loaded-library lifetime) — leaks or dangling stubs are now your responsibility, just safely surfaced. 6. **Binding effort for real libraries.** Hand-writing layouts/descriptors for a large C header is tedious and error-prone; the **`jextract`** tool generates Java bindings from headers and is effectively required for non-trivial libraries (and is itself a separate, evolving tool). 7. **Migration cost off Unsafe/JNI.** Existing JNI/Unsafe code must be rewritten; for stable, working JNI with heavy investment the payoff may not justify immediate migration — though the looming Unsafe removal makes migrating off `Unsafe` non-optional eventually. ## A decision rubric - **New off-heap memory need** → FFM (safe, public, no 2GB cap). Avoid `Unsafe`. - **New native-library interop** → FFM + jextract; reach for JNI only for niche constraints (e.g. needing JNI-specific behaviors or a sub-22 runtime you can't move off). - **Existing `Unsafe` usage** → plan migration to FFM (or VarHandles) ahead of `Unsafe` removal. - **Existing working JNI** → migrate opportunistically, prioritizing crash-prone or maintenance-heavy bindings. - **Operationally** → standardize the `--enable-native-access` flags, isolate native bindings behind a thin, well-tested module, and own arena/stub lifetimes explicitly. ## Bottom line FFM is the strategic, safe, standard successor: pure-Java bindings, memory safety, and performance, enabling the JDK to drop `Unsafe`. The residual risks are version requirements, the opt-in native-access model, unavoidable boundary cost, and the fact that the *native side* can still misbehave — so treat FFM as a much safer tool, not a guarantee that native interop is risk-free.