What are the main pitfalls of memory-mapped files in Java — resource cleanup, the 2 GB limit, and crash safety — and how do you address them?

## Why memory mapping bites back Memory mapping is powerful but leaks abstraction: you're manipulating OS virtual-memory state through a Java object whose lifecycle is governed by the garbage collector, not by you. Three concrete pitfalls follow. ### 1. Non-deterministic cleanup (the unmap problem) Standard Java provides **no public, portable `unmap()`** for a `MappedByteBuffer` (before the FFM API). The underlying OS mapping is torn down only when the buffer becomes **unreachable and is garbage-collected**, and even then at the GC's discretion. Consequences: - The file remains *mapped* until GC runs. On **Windows**, a mapped file typically cannot be **deleted, renamed, or truncated** — so a `Files.delete(path)` may fail with the file "in use" even after you closed the channel. - You cannot deterministically free the address-space and page-cache resources, which matters for many/large mappings. Workarounds historically used the internal `sun.misc.Cleaner`/`Unsafe.invokeCleaner` hack — fragile and discouraged. The clean modern answer is the **Foreign Function & Memory API** (`java.lang.foreign`, stable in Java 21+): `Arena.ofConfined()` plus `FileChannel.map(mode, off, size, arena)` gives a `MemorySegment` whose mapping is **deterministically released when the Arena is closed** (try-with-resources). If you must stay on classic NIO, the practical advice is: keep `MappedByteBuffer`s **short-lived and out of scope**, minimize their count, and don't rely on freeing them at a precise moment. ### 2. The ~2 GB per-mapping limit `FileChannel.map` takes a `long size`, but a `MappedByteBuffer` extends `ByteBuffer`, whose **capacity is an `int`**. Maximum single mapping = `Integer.MAX_VALUE` ≈ 2.1 GB. To map a larger file with classic NIO you **window** it: create several mappings of ≤2 GB each and route each access to the mapping covering that offset. This adds bookkeeping (which window, boundary-straddling reads). The FFM API removes this limit — `MemorySegment` mappings use `long` sizing. ### 3. Crash safety and truncation hazards - **Durability:** mapped writes land in the page cache and are written back lazily; they are durable only after `force()` (see the force/durability topic). A power loss before flush loses them. - **SIGBUS on shrink:** if the underlying file is **truncated** (by you or another process) so that a mapped region no longer corresponds to real file contents, touching that region can deliver a **SIGBUS**, which typically **crashes the JVM** (it's a hardware-level signal, not a catchable Java exception). So never shrink a file out from under a live mapping; coordinate truncation with mapping lifecycle, and on some platforms you must also drop the mapping before changing file length. - **Stale views:** other processes mapping/writing the same file can change data you're reading; combine with `FileLock` if you need consistency. ## Putting it together: a safe pattern ```java // Classic NIO: window large files, force at checkpoints, scope the buffer tightly. long chunk = Integer.MAX_VALUE; // ~2 GB for (long pos = 0; pos < size; pos += chunk) { long len = Math.min(chunk, size - pos); MappedByteBuffer w = ch.map(READ_WRITE, pos, len); // ... process window ... w.force(); // durability at the window boundary // let w go out of scope; do not truncate the file while mappings live } ``` For new code on Java 21+, prefer the FFM API for deterministic unmap and large mappings. ## Summary The three classic memory-mapping pitfalls are: (1) cleanup is GC-bound with no portable unmap (file stays locked, esp. on Windows); (2) one mapping is capped at ~2 GB; (3) writes aren't durable until force(), and truncating a file under a live mapping can SIGBUS-crash the JVM. Mitigate with short-lived/windowed mappings, force() at checkpoints, careful truncation handling, or the Java 21+ FFM API for deterministic close and large mappings.