Java ThreadLocal Leak — Missing remove() Cost 2.8GB Heap

package io.thecodeforge.memory;

import java.util.ArrayList;
import java.util.List;

/**
 * Demonstrates the difference between an object being logically 'done'
 * and being GC-eligible. The GC cannot read intent — only references.
 *
 * Run with: java -Xmx64m io.thecodeforge.memory.ReachabilityDemo
 * You will see OOM in roughly 60 iterations with a 64MB heap.
 */
public class ReachabilityDemo {

    /**
     * Static field == GC root.
     * Anything added here is permanently reachable and NEVER collected.
     * The GC sees a live reference chain from the class → CACHE → each byte[].
     * It has no way to know that our business logic is done with those arrays.
     */
    private static final List<byte[]> CACHE = new ArrayList<>();

    public static void main(String[] args) throws InterruptedException {
        System.out.println("Simulating a static-field memory leak...");
        System.out.println("Watch the heap baseline rise — it never drops.");
        System.out.println();

        for (int iteration = 0; iteration < 1000; iteration++) {
            // Each byte array is 1 MB. Business logic is 'done' with it
            // after this method call, but CACHE still holds a reference.
            byte[] oneMegabyte = new byte[1024 * 1024];
            oneMegabyte[0] = (byte) iteration; // use it so the compiler keeps it

            CACHE.add(oneMegabyte); // <-- this is the leak

            // The GC runs frequently but the old-gen baseline never drops.
            // Each iteration pushes the floor higher by 1MB.

            System.out.printf(
                "Iteration %3d | CACHE entries: %3d | Heap used: %3d MB%n",
                iteration,
                CACHE.size(),
                (Runtime.getRuntime().totalMemory()
                    - Runtime.getRuntime().freeMemory()) / (1024 * 1024)
            );

            Thread.sleep(50);
        }
    }
}

package io.thecodeforge.memory;

import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;

/**
 * Demonstrates a ThreadLocal memory leak inside a fixed thread pool.
 *
 * The pool reuses threads. ThreadLocal values set in one task remain
 * in the thread's ThreadLocalMap when the next task starts on the same thread.
 *
 * Run with: java -Xmx128m io.thecodeforge.memory.ThreadLocalLeakDemo
 * Watch heap climb with the fix commented out.
 * Uncomment REQUEST_CONTEXT.remove() to see heap stay flat.
 */
public class ThreadLocalLeakDemo {

    /**
     * ThreadLocal is NOT a variable. It is a key into a hidden
     * Map<ThreadLocal, Object> that lives on each Thread object.
     * When the Thread dies, the map is collected.
     * In a thread pool, threads never die — so neither do forgotten entries.
     */
    private static final ThreadLocal<byte[]> REQUEST_CONTEXT = new ThreadLocal<>();

    public static void main(String[] args) throws InterruptedException {
        // 4 threads — they live forever, accumulating stale ThreadLocal values
        ExecutorService threadPool = Executors.newFixedThreadPool(4);

        for (int taskNumber = 0; taskNumber < 500; taskNumber++) {
            final int currentTask = taskNumber;

            threadPool.submit(() -> {
                try {
                    // Simulating per-request data: user session, trace context,
                    // transaction payload — anything you would not want pinned
                    // to the thread after the request is done.
                    byte[] requestPayload = new byte[500 * 1024]; // 500 KB
                    requestPayload[0] = (byte) currentTask;
                    REQUEST_CONTEXT.set(requestPayload);

                    processRequest(currentTask);

                    // Without remove(), requestPayload stays in this thread's
                    // ThreadLocalMap after the task completes. The thread goes
                    // back to the pool. The reference is never cleared.
                    // 4 threads × accumulating entries = unbounded growth.

                } finally {
                    // THE FIX: uncomment this line to prevent the leak.
                    // This is the single most important line in thread pool code
                    // that uses ThreadLocal.
                    // REQUEST_CONTEXT.remove();
                }
            });

            if (currentTask % 50 == 0) {
                long usedHeapMB = (Runtime.getRuntime().totalMemory()
                    - Runtime.getRuntime().freeMemory()) / (1024 * 1024);
                System.out.printf(
                    "Tasks submitted: %3d | Heap used: ~%d MB%n",
                    currentTask, usedHeapMB
                );
            }
        }

        threadPool.shutdown();
        threadPool.awaitTermination(30, TimeUnit.SECONDS);
        System.out.println("Done. Check heap trend above.");
    }

    private static void processRequest(int taskNumber) {
        byte[] context = REQUEST_CONTEXT.get();
        // In production: this might be a UserSession, PaymentContext,
        // MDC trace ID, or any per-request state.
        System.out.printf("Task %3d on thread: %s | context bytes: %d%n",
            taskNumber,
            Thread.currentThread().getName(),
            context != null ? context.length : 0
        );
    }
}

package io.thecodeforge.memory;

import java.lang.ref.SoftReference;
import java.lang.ref.WeakReference;
import java.util.WeakHashMap;

/**
 * Side-by-side comparison of Strong, Soft, and Weak references.
 * Shows WeakHashMap auto-eviction and the String literal gotcha.
 *
 * Run with: java -Xmx32m io.thecodeforge.memory.ReferenceTypesDemo
 */
public class ReferenceTypesDemo {

    public static void main(String[] args) throws InterruptedException {
        demonstrateSoftReference();
        demonstrateWeakHashMap();
        demonstrateStringLiteralGotcha();
    }

    private static void demonstrateSoftReference() {
        System.out.println("=== SoftReference: cleared only under memory pressure ===");

        byte[] expensiveData = new byte[10 * 1024 * 1024]; // 10 MB
        SoftReference<byte[]> softCache = new SoftReference<>(expensiveData);

        // Drop the strong reference — only the soft reference holds the data now
        expensiveData = null;

        System.out.println("Before pressure — data available: "
            + (softCache.get() != null)); // true

        // Simulate memory pressure — forces GC to consider clearing soft refs
        try {
            byte[] pressureBlock = new byte[25 * 1024 * 1024];
            System.out.println("Allocated pressure block: " + pressureBlock.length + " bytes");
        } catch (OutOfMemoryError oom) {
            System.out.println("OOM — JVM cleared soft refs before throwing");
        }

        System.out.println("After pressure  — data available: "
            + (softCache.get() != null)); // likely false
        System.out.println();
    }

    private static void demonstrateWeakHashMap() throws InterruptedException {
        System.out.println("=== WeakHashMap: entry lives only as long as the key ===");

        WeakHashMap<Object, String> metadataCache = new WeakHashMap<>();

        // Use Object as key — a domain object that has no other references.
        // This simulates caching metadata about a parsed AST node.
        Object sessionKey = new Object();
        metadataCache.put(sessionKey, "{ role: admin, locale: en-US }");

        System.out.println("Cache size before GC: " + metadataCache.size()); // 1

        // Drop the only strong reference to the key
        sessionKey = null;

        System.gc();
        Thread.sleep(200); // give GC time to run

        // WeakHashMap expunges stale entries on the next map operation
        System.out.println("Cache size after GC:   " + metadataCache.size()); // 0
        System.out.println("Entry auto-evicted — no manual removal needed!");
        System.out.println();
    }

    private static void demonstrateStringLiteralGotcha() throws InterruptedException {
        System.out.println("=== String literal key: the WeakHashMap gotcha ===");

        WeakHashMap<String, String> brokenCache = new WeakHashMap<>();

        // String literals are interned — the JVM string pool holds a permanent
        // strong reference to them. This key will NEVER be collected.
        // The WeakHashMap entry stays forever.
        String literalKey = "my-session-key"; // interned — permanent strong ref
        brokenCache.put(literalKey, "some cached value");

        // Setting literalKey = null does NOT clear the intern pool reference.
        // The string pool retains the strong reference.
        literalKey = null;

        System.gc();
        Thread.sleep(200);

        System.out.println("Cache size after GC with String literal key: "
            + brokenCache.size()); // still 1 — entry was NOT evicted
        System.out.println("This WeakHashMap will grow forever with String literal keys.");
        System.out.println("Fix: use 'new String(key)' or a domain object as the key.");
        System.out.println("Better fix: use Caffeine with expireAfterWrite and maximumSize.");
    }
}

package io.thecodeforge.memory;

/**
 * Production leak detection configuration reference.
 *
 * Add JVM flags to your startup configuration:
 * - Docker: ENV JAVA_OPTS in Dockerfile or docker-compose
 * - Kubernetes: spec.containers[].env in deployment manifest
 * - systemd: Environment= in unit file
 *
 * =====================================================================
 * MANDATORY JVM FLAGS FOR PRODUCTION LEAK DETECTION
 * =====================================================================
 *
 * # Automatic heap dump on OutOfMemoryError — non-negotiable
 * -XX:+HeapDumpOnOutOfMemoryError
 * -XX:HeapDumpPath=/var/log/myapp/heapdumps/
 *
 * # GC logging — sawtooth pattern confirms health, rising baseline confirms leak
 * -Xlog:gc*:file=/var/log/myapp/gc.log:time,uptime:filecount=5,filesize=20m
 *
 * # Native memory tracking — for off-heap and metaspace leaks
 * -XX:NativeMemoryTracking=summary
 *
 * # G1 is default in JDK 9+ and suitable for most workloads
 * -XX:+UseG1GC
 * -XX:MaxGCPauseMillis=200
 *
 * =====================================================================
 * LIVE DIAGNOSTIC COMMANDS (no restart required)
 * =====================================================================
 *
 * # Find the JVM process ID
 * $ jps -l
 * 18423 io.thecodeforge.service.PaymentService
 *
 * # Trigger a heap dump without stopping the process
 * # Preferred over jmap in production — safer code path in JDK 9+
 * $ jcmd 18423 GC.heap_dump /tmp/heapdump-$(date +%Y%m%d-%H%M%S).hprof
 *
 * # Class histogram — top memory consumers by class type
 * # Take two snapshots 10 minutes apart and diff them
 * $ jcmd 18423 GC.class_histogram | head -30
 *
 * # GC occupancy — watch Old/O for rising baseline across collections
 * # O = old gen occupancy, S0/S1 = survivor spaces, E = eden
 * $ jstat -gcutil 18423 1000 30
 *
 * # Native memory summary — catches metaspace and direct buffer leaks
 * $ jcmd 18423 VM.native_memory summary
 *
 * # Thread dump — needed for ThreadLocal leak analysis
 * $ jcmd 18423 Thread.print > /tmp/threaddump.txt
 *
 * # Start JFR recording — near-zero overhead, runs in production
 * # Look for jdk.OldObjectSample events for long-lived object tracking
 * $ jcmd 18423 JFR.start duration=300s filename=/tmp/recording.jfr settings=profile
 *
 * =====================================================================
 * INTERPRETING A CLASS HISTOGRAM
 * =====================================================================
 *
 * num   #instances   #bytes   class name
 * ---   ----------   ------   ----------
 *   1:    950,234    22.8MB   [B (byte arrays)
 *   2:    420,000    13.4MB   io.thecodeforge.model.UserSession
 *   3:    420,000     6.7MB   java.util.HashMap$Node
 *
 * If UserSession count grows monotonically across two snapshots,
 * and HashMap$Node count matches it (UserSession has a HashMap field),
 * you almost certainly have a session or cache without eviction.
 *
 * The 1:1 ratio between UserSession and HashMap$Node is a strong signal
 * that the same objects are being accumulated — not coincidentally similar counts.
 */
public class LeakDetectionSetup {

    public static void main(String[] args) {
        System.out.println("See Javadoc above for production JVM configuration.");
        System.out.println();

        // Runtime heap stats — useful for a /health/memory endpoint
        Runtime jvmRuntime = Runtime.getRuntime();
        long maxHeapMB   = jvmRuntime.maxMemory()   / (1024 * 1024);
        long totalHeapMB = jvmRuntime.totalMemory()  / (1024 * 1024);
        long freeHeapMB  = jvmRuntime.freeMemory()   / (1024 * 1024);
        long usedHeapMB  = totalHeapMB - freeHeapMB;

        System.out.printf("Max heap:   %6d MB%n", maxHeapMB);
        System.out.printf("Used heap:  %6d MB%n", usedHeapMB);
        System.out.printf("Free heap:  %6d MB%n", freeHeapMB);
        System.out.printf("Usage:      %6.1f%%%n",
            (double) usedHeapMB / maxHeapMB * 100);
    }
}