Java Garbage Collection Internals: GC Algorithms, Tuning & Production Gotchas

package io.thecodeforge.gc;

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

/**
 * Demonstrates how Java GC determines object reachability.
 *
 * Key concept: An object is reachable if any GC root can access it
 * through a chain of references. When the chain breaks, the object
 * becomes eligible for collection.
 */
public class ReachabilityDemo {

    public static void main(String[] args) {
        // Object created on the heap — referenced by local variable 'order'
        // 'order' is a GC root (stack reference)
        Order order = new Order("ORD-001", 149.99);
        System.out.println("Order created: " + order.getId());

        // After this reassignment, the original Order object has no
        // reachable references. It becomes eligible for GC.
        order = new Order("ORD-002", 299.99);
        // The first Order("ORD-001") is now unreachable — GC will reclaim it

        // Demonstrating cyclic references — GC handles this correctly
        OrderNode nodeA = new OrderNode("A");
        OrderNode nodeB = new OrderNode("B");
        nodeA.next = nodeB;
        nodeB.next = nodeA; // cycle: A -> B -> A

        // Even though A and B reference each other, if we null out
        // our stack references, both become unreachable and are collected
        nodeA = null;
        nodeB = null;
        // The cycle A -> B -> A is still intact in memory, but no GC root
        // can reach either node. Both are eligible for collection.
    }

    static class Order {
        private final String id;
        private final double amount;

        Order(String id, double amount) {
            this.id = id;
            this.amount = amount;
        }

        String getId() { return id; }
    }

    static class OrderNode {
        final String name;
        OrderNode next;

        OrderNode(String name) {
            this.name = name;
        }
    }
}

package io.thecodeforge.gc;

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

/**
 * Demonstrates how allocation patterns interact with the generational heap.
 *
 * Objects that survive young collections are promoted to old generation.
 * Understanding this promotion mechanism is critical for tuning.
 */
public class GenerationalBehaviorDemo {

    /**
     * Pattern 1: Short-lived objects — ideal for generational GC.
     * These objects die in eden and never reach old generation.
     * GC can reclaim them with a fast young collection.
     */
    public void processRequest() {
        // These objects are created, used, and become unreachable
        // within a single method call. They die in eden.
        String requestId = java.util.UUID.randomUUID().toString();
        byte[] payload = new byte[4096];
        List<String> validationErrors = new ArrayList<>();

        // After this method returns, all three objects become unreachable
        // because they are only referenced by local variables (stack roots).
    }

    /**
     * Pattern 2: Long-lived cached objects — promoted to old gen.
     * These objects survive young collections and get promoted.
     * They occupy old generation permanently (or until eviction).
     *
     * Production risk: If this cache grows unbounded, old generation
     * fills up and triggers full GC or OOM.
     */
    private final List<byte[]> longLivedCache = new ArrayList<>();

    public void cacheData(byte[] data) {
        // This reference keeps the byte array alive indefinitely.
        // After surviving MaxTenuringThreshold young collections,
        // it is promoted to old generation.
        longLivedCache.add(data);
    }

    /**
     * Pattern 3: Premature promotion — objects that should die young
     * but get promoted because survivor space is full.
     *
     * If allocation rate exceeds survivor space capacity, objects
     * are promoted directly to old generation even if they are short-lived.
     * This is called premature promotion and it pollutes old generation.
     *
     * Fix: Increase survivor space ratio (-XX:SurvivorRatio)
     *       or reduce allocation rate.
     */
    public void burstAllocation() {
        // If this loop runs fast enough to fill eden AND overflow
        // survivor space, these temporary objects get promoted to
        // old generation even though they die after each iteration.
        for (int i = 0; i < 100_000; i++) {
            byte[] temp = new byte[256];
            // temp is short-lived, but under pressure it may be
            // prematurely promoted to old generation
        }
    }

    /**
     * Production tuning flags for generational behavior:
     *
     * -XX:NewRatio=2              // old:young = 2:1 (default for most collectors)
     * -XX:SurvivorRatio=8         // eden:survivor = 8:1 (default)
     * -XX:MaxTenuringThreshold=15 // objects survive 15 young GCs before promotion
     * -XX:+AlwaysTenure            // promote immediately (dangerous — avoid)
     * -XX:+NeverTenure             // never promote (survivor overflow → old gen)
     *
     * Monitor promotion rate with:
     *   jstat -gcutil <pid> 1000
     *   Watch 'O' column (old gen utilization) for steady growth.
     *   Steady growth with low live data = premature promotion.
     */
}

package io.thecodeforge.gc;

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

/**
 * Demonstrates how different GC algorithm characteristics
 * affect production behavior.
 *
 * This is not a GC implementation — it illustrates the concepts
 * that drive real collector design decisions.
 */
public class GCAlgorithmDemo {

    /**
     * MARK-AND-SWEEP characteristic:
     * - Fast reclaim but creates fragmentation
     * - External fragmentation: total free > requested, but not contiguous
     *
     * Production impact: After hours of operation, allocation of large
     * objects fails even though 40% of heap is free — it's fragmented.
     * This triggers unnecessary full GC or OOM.
     */
    public void demonstrateFragmentation() {
        // Imagine this array is the heap, each index is a memory block
        // true = occupied, false = free
        boolean[] heap = new boolean[100];

        // Simulate allocation pattern: allocate and free alternating blocks
        for (int i = 0; i < 100; i++) {
            heap[i] = true; // allocate
        }
        for (int i = 0; i < 100; i += 2) {
            heap[i] = false; // free every other block
        }
        // Result: 50% free, but no contiguous block of size > 1
        // A request for 3 contiguous blocks fails despite 50 free blocks
        // This is external fragmentation — the problem compaction solves
    }

    /**
     * COPYING COLLECTOR characteristic:
     * - Copies live objects to to-space, discards from-space
     * - Inherently compacting — no fragmentation
     * - Cost: proportional to live data, not dead data
     * - Requires double the memory (from + to spaces)
     *
     * Production insight: Copying cost is why large live data sets
     * cause longer young collection pauses. If your service has
     * 2GB of live objects in young gen, copying takes measurable time.
     */
    public void demonstrateCopyingCost() {
        // Simulating live data that must be copied during young GC
        List<byte[]> liveObjects = new ArrayList<>();
        for (int i = 0; i < 10_000; i++) {
            liveObjects.add(new byte[1024]); // 1KB each = ~10MB live data
        }

        // During young GC, all 10MB must be copied to survivor space.
        // If only 1MB were live, the cost would be 10x lower.
        // This is why reducing live data in young gen reduces pause time.
        //
        // Real production fix: avoid holding references to temporary
        // objects across request boundaries. Let them die in eden.
    }
}

package io.thecodeforge.gc;

import java.util.concurrent.ConcurrentHashMap;
import java.util.Map;

/**
 * Demonstrates allocation patterns that stress G1 differently.
 *
 * Key insight: G1 humongous objects (>50% region size) bypass normal
 * allocation and can trigger to-space exhausted failures.
 */
public class G1TuningExample {

    // Cache with large value objects — common source of humongous allocations
    private final Map<String, byte[]> payloadCache = new ConcurrentHashMap<>();

    /**
     * BAD: Allocates objects that may exceed humongous threshold.
     * With default 1MB region size, objects > 512KB are humongous.
     * With 32MB regions, threshold is 16MB — much safer for large payloads.
     *
     * Tuning: -XX:G1HeapRegionSize=32M
     *         -XX:G1ReservePercent=15
     *         -XX:InitiatingHeapOccupancyPercent=35
     */
    public void cacheLargePayload(String key, int sizeBytes) {
        byte[] payload = new byte[sizeBytes];
        for (int i = 0; i < Math.min(sizeBytes, 1024); i++) {
            payload[i] = (byte) (i & 0xFF);
        }
        payloadCache.put(key, payload);
    }

    /**
     * BETTER: Chunk large payloads to stay below humongous threshold.
     * Each chunk is independently collectible as a regular object.
     */
    public void cacheChunkedPayload(String key, byte[] fullPayload) {
        int chunkSize = 256 * 1024; // 256KB chunks
        int numChunks = (fullPayload.length + chunkSize - 1) / chunkSize;

        for (int i = 0; i < numChunks; i++) {
            int offset = i * chunkSize;
            int length = Math.min(chunkSize, fullPayload.length - offset);
            byte[] chunk = new byte[length];
            System.arraycopy(fullPayload, offset, chunk, 0, length);
            payloadCache.put(key + ":chunk:" + i, chunk);
        }
    }

    /**
     * Production G1 flags for a 16GB heap with mixed allocation profile:
     *
     * -XX:+UseG1GC
     * -Xms16g -Xmx16g
     * -XX:G1HeapRegionSize=16m
     * -XX:MaxGCPauseMillis=200
     * -XX:G1ReservePercent=15
     * -XX:InitiatingHeapOccupancyPercent=35
     * -XX:G1MixedGCCountTarget=8
     * -XX:G1MixedGCLiveThresholdPercent=85
     * -Xlog:gc*,gc+humongous=debug:file=/var/log/gc.log:time,uptime,level,tags
     */
}

package io.thecodeforge.gc;

import java.util.concurrent.atomic.AtomicLong;

/**
 * ZGC-specific considerations for production workloads.
 *
 * ZGC trades per-access overhead for near-zero pause times.
 * The load barrier adds ~4-8% overhead on pointer-heavy workloads.
 */
public class ZGCTuningExample {

    private final AtomicLong allocationCounter = new AtomicLong(0);

    /**
     * Production ZGC flags for a 32GB heap, latency-sensitive service:
     *
     * -XX:+UseZGC
     * -XX:+ZGenerational              // JDK 21+ — critical for throughput
     * -Xms32g -Xmx32g                // Always set Xms=Xmx for ZGC
     * -XX:SoftMaxHeapSize=28g         // ZGC-specific: target heap occupancy
     * -XX:ZCollectionInterval=5       // Suggest GC cycle every 5 seconds
     * -XX:ConcGCThreads=4             // Concurrent GC threads
     * -Xlog:gc*:file=/var/log/zgc.log:time,uptime,level,tags
     *
     * CRITICAL: ZGC uses ~20% native memory overhead beyond -Xmx.
     * Container memory limit must be heap * 1.25 minimum.
     */

    /**
     * ZGC SoftMaxHeapSize is unique — it tells ZGC to try to stay below
     * this threshold but can exceed it under allocation pressure.
     *
     * Use case: Set heap to 32GB, SoftMaxHeapSize to 28GB.
     * ZGC will trigger cycles aggressively to stay under 28GB.
     * Only allocates into the remaining 4GB under extreme pressure.
     */
    public void demonstrateSoftMaxHeapConcept() {
        // With SoftMaxHeapSize=28g and Xmx=32g:
        // - ZGC targets 28GB occupancy
        // - If allocation pressure pushes past 28GB, ZGC cycles more aggressively
        // - If it hits 32GB, allocation stalls (not OOM, but backpressure)
    }
}

package io.thecodeforge.gc;

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

/**
 * Shenandoah-specific production considerations.
 *
 * Shenandoah uses Brooks pointers — every object has an extra forwarding
 * pointer field. This adds 8 bytes per object on 64-bit systems.
 */
public class ShenandoahTuningExample {

    /**
     * Brooks pointer overhead calculation:
     *
     * Object with 2 fields (16 bytes header + 16 bytes data = 32 bytes)
     * + 8 bytes Brooks pointer = 40 bytes per object
     * Overhead: 25% increase per object
     *
     * For 10 million small objects: ~80MB additional memory
     * For 100 million small objects: ~800MB additional memory
     */
    public long estimateBrooksOverhead(int objectCount) {
        return (long) objectCount * 8;
    }

    /**
     * Production Shenandoah flags for a 16GB heap:
     *
     * -XX:+UseShenandoahGC
     * -Xms16g -Xmx16g
     * -XX:ShenandoahGCHeuristics=adaptive
     * -XX:ShenandoahAllocationThreshold=10
     * -XX:+UseCompressedOops               // works with Shenandoah (unlike ZGC)
     * -Xlog:gc*:file=/var/log/shenandoah.log:time,uptime,level,tags
     */

    /**
     * Shenandoah pacing is a unique feature that backpressures allocation
     * threads when the collector falls behind.
     *
     * Unlike ZGC which stalls allocation entirely, Shenandoah slows down
     * allocating threads proportionally. This creates smoother latency
     * degradation under load rather than sharp spikes.
     */
    public void demonstratePacingBehavior() {
        List<byte[]> allocations = new ArrayList<>();

        // Under heavy allocation, Shenandoah will pace this loop
        // by adding small delays to each allocation.
        // The delay is proportional to how far behind the collector is.
        for (int i = 0; i < 100_000; i++) {
            allocations.add(new byte[1024]);
        }
    }
}

package io.thecodeforge.gc;

/**
 * Production JVM flag configurations organized by collector.
 * These are starting points — tune based on measured workload characteristics.
 */
public class ProductionJVMFlags {

    /**
     * UNIVERSAL FLAGS (apply to all collectors):
     *
     * -Xms<size> -Xmx<size>         // Set min=max to avoid resize overhead
     * -XX:+AlwaysPreTouch             // Pre-zero heap pages at startup
     * -XX:+DisableExplicitGC          // Ignore System.gc() calls
     * -XX:+HeapDumpOnOutOfMemoryError // Auto heap dump on OOM
     * -XX:HeapDumpPath=/var/log/      // Where to write heap dumps
     * -XX:+UseContainerSupport        // Respect cgroup limits (default JDK 10+)
     * -XX:MaxRAMPercentage=75.0       // Set heap as % of container memory
     * -XX:NativeMemoryTracking=detail // Track off-heap memory usage
     *
     * LOGGING FLAGS (always enable in production):
     * -Xlog:gc*:file=/var/log/gc.log:time,uptime,level,tags:filecount=5,filesize=50m
     *
     * CRITICAL: Never set -Xmx equal to container memory limit.
     * JVM needs native memory for threads, metaspace, GC structures.
     * Rule: container_limit = Xmx * 1.15 (G1) or Xmx * 1.25 (ZGC)
     */

    /**
     * G1-SPECIFIC FLAGS:
     *
     * -XX:+UseG1GC
     * -XX:G1HeapRegionSize=<1-32m>    // Must be power of 2, 1MB-32MB
     * -XX:MaxGCPauseMillis=200        // Soft target (default 200ms)
     * -XX:InitiatingHeapOccupancyPercent=45  // When to start concurrent mark
     * -XX:G1ReservePercent=10         // Reserve buffer for evacuation
     * -XX:G1MixedGCCountTarget=8      // Spread mixed GC over N cycles
     * -XX:G1MixedGCLiveThresholdPercent=85  // Skip regions with >85% live
     *
     * When to adjust:
     * - Humongous objects → increase G1HeapRegionSize
     * - Frequent full GC → decrease InitiatingHeapOccupancyPercent to 35
     * - Long mixed GC pauses → increase G1MixedGCCountTarget
     */

    /**
     * ZGC-SPECIFIC FLAGS:
     *
     * -XX:+UseZGC
     * -XX:+ZGenerational              // JDK 21+ — ALWAYS enable
     * -XX:SoftMaxHeapSize=<size>      // Target occupancy (ZGC-specific)
     * -XX:ConcGCThreads=<count>       // Concurrent threads (default: auto)
     * -XX:+ZUncommit                  // Return unused memory to OS
     * -XX:ZUncommitDelay=300          // Seconds before uncommitting
     *
     * CRITICAL: ZGC does not support compressed oops.
     * On heaps < 32GB, this means ~15% more memory usage than G1.
     */

    /**
     * SHENANDOAH-SPECIFIC FLAGS:
     *
     * -XX:+UseShenandoahGC
     * -XX:ShenandoahGCHeuristics=adaptive  // adaptive, compact, or static
     * -XX:ShenandoahAllocationThreshold=10 // cycle after N% allocation
     * -XX:+UseCompressedOops              // Supported (unlike ZGC)
     *
     * Heuristic modes:
     * - adaptive: adjusts cycle frequency based on allocation rate (default)
     * - compact: more aggressive collection, lower heap usage
     * - static: fixed cycle interval, good for benchmarking
     */
}