Memory Management

Memory Management

This guide covers advanced memory management techniques for rendering in Minecraft 26.1, including buffer pooling, resource lifecycle optimization, and memory leak prevention strategies.

Advanced Buffer Management

Ring Buffer Pattern

Minecraft uses ring buffers for efficient uniform data management:

net.minecraft.client.renderer.DynamicUniformStorage

public class DynamicUniformStorage {
    private MappableRingBuffer ringBuffer;
    private final List<MappableRingBuffer> oldBuffers = new ArrayList<>();
    private int capacity;
    private final int blockSize;

    public DynamicUniformStorage(String label, int initialCapacity, int blockSize) {
        this.blockSize = blockSize;
        this.capacity = initialCapacity;
        this.ringBuffer = new MappableRingBuffer(() -> label + " x" + blockSize,
                                                130, blockSize * initialCapacity);
    }

    private void resizeBuffers(final int newCapacity) {
        this.capacity = newCapacity;
        this.oldBuffers.add(this.ringBuffer);
        this.ringBuffer = new MappableRingBuffer(() -> this.label + " x" + this.blockSize,
                                                 130, this.blockSize * newCapacity);
    }

    private int writeUniforms(final int firstIndex, final int count, final byte[] uniforms) {
        int bytesWritten = 0;

        while (bytesWritten < count) {
            int availableBytes = this.ringBuffer.availableBytes();
            if (availableBytes == 0) {
                this.increaseRingBuffer(this.blockSize);
                continue;
            }

            int bytesToWrite = Math.min(count - bytesWritten, availableBytes);
            this.ringBuffer.writeBytes(uniforms, bytesWritten, bytesToWrite);
            bytesWritten += bytesToWrite;
        }

        return bytesWritten;
    }

    private void increaseRingBuffer(final int additionalCapacity) {
        if (this.capacity + additionalCapacity > 16384) {
            throw new IllegalStateException("Uniform storage overflow");
        }
        this.resizeBuffers(this.capacity + additionalCapacity);
    }
}

Buffer Pool Management

Implement efficient buffer pooling to reduce memory allocations:

// Example: Advanced buffer pool system
public class AdvancedBufferPool {
    private final Map<Integer, Queue<GpuBuffer>> bufferPools = new ConcurrentHashMap<>();
    private final Map<GpuBuffer, BufferMetadata> activeBuffers = new ConcurrentHashMap<>();
    private final ScheduledExecutorService cleanupExecutor =
        Executors.newSingleThreadScheduledExecutor();

    private static class BufferMetadata {
        final long creationTime;
        final long lastUsedTime;
        final int size;
        final String stackTrace;

        BufferMetadata(int size) {
            this.size = size;
            this.creationTime = System.currentTimeMillis();
            this.lastUsedTime = System.currentTimeMillis();
            this.stackTrace = getStackTrace();
        }

        void updateLastUsed() {
            // Update last used time when buffer is accessed
        }
    }

    public GpuBuffer acquireBuffer(int size, GpuBuffer.BufferType type) {
        Queue<GpuBuffer> pool = bufferPools.computeIfAbsent(size, k -> new ConcurrentLinkedQueue<>());
        GpuBuffer buffer = pool.poll();

        if (buffer == null || !buffer.isValid()) {
            buffer = createNewBuffer(size, type);
        }

        activeBuffers.put(buffer, new BufferMetadata(size));
        return buffer;
    }

    public void releaseBuffer(GpuBuffer buffer) {
        BufferMetadata metadata = activeBuffers.remove(buffer);
        if (metadata != null) {
            int size = metadata.size;
            Queue<GpuBuffer> pool = bufferPools.get(size);
            if (pool != null) {
                buffer.clear();
                pool.offer(buffer);
            }
        }
    }

    public void cleanup() {
        // Remove old buffers that haven't been used recently
        long currentTime = System.currentTimeMillis();
        long maxAge = TimeUnit.MINUTES.toMillis(5);

        bufferPools.forEach((size, pool) -> {
            pool.removeIf(buffer -> {
                BufferMetadata metadata = activeBuffers.get(buffer);
                return metadata == null ||
                       (currentTime - metadata.lastUsedTime) > maxAge;
            });
        });
    }

    public void startAutomaticCleanup() {
        cleanupExecutor.scheduleAtFixedRate(this::cleanup, 1, 1, TimeUnit.MINUTES);
    }

    public void diagnoseLeaks() {
        System.out.println("=== Buffer Leak Diagnosis ===");
        activeBuffers.forEach((buffer, metadata) -> {
            System.out.printf("Leaked buffer: size=%d, age=%dms%n",
                            metadata.size,
                            System.currentTimeMillis() - metadata.creationTime);
            System.out.println("Creation stack trace:");
            System.out.println(metadata.stackTrace);
        });
    }
}

Dynamic Buffer Resizing

Implement intelligent buffer resizing with memory tracking:

// Example: Dynamic buffer with growth strategy
public class DynamicResizableBuffer {
    private ByteBufferBuilder bufferBuilder;
    private final long maxCapacity;
    private final float growthFactor;
    private long currentCapacity;
    private long usedBytes = 0;
    private final MemoryTracker memoryTracker;

    public DynamicResizableBuffer(long initialCapacity, long maxCapacity,
                                 float growthFactor) {
        this.maxCapacity = maxCapacity;
        this.growthFactor = growthFactor;
        this.currentCapacity = initialCapacity;
        this.bufferBuilder = new ByteBufferBuilder((int) initialCapacity);
        this.memoryTracker = new MemoryTracker();

        memoryTracker.allocate(initialCapacity);
    }

    public void ensureCapacity(long requiredCapacity) {
        if (requiredCapacity > currentCapacity) {
            resize(requiredCapacity);
        }
    }

    private void resize(long newCapacity) {
        if (newCapacity > maxCapacity) {
            throw new OutOfMemoryError("Buffer capacity exceeded maximum: " + maxCapacity);
        }

        long oldCapacity = currentCapacity;
        currentCapacity = Math.min(newCapacity,
                                   Math.min((long) (oldCapacity * growthFactor), maxCapacity));

        ByteBufferBuilder oldBuffer = bufferBuilder;
        bufferBuilder = new ByteBufferBuilder((int) currentCapacity);

        // Copy existing data
        if (usedBytes > 0) {
            byte[] data = oldBuffer.extractData(0, (int) usedBytes);
            bufferBuilder.putBytes(data);
        }

        // Update memory tracking
        memoryTracker.deallocate(oldCapacity);
        memoryTracker.allocate(currentCapacity);

        // Schedule cleanup of old buffer
        scheduleBufferCleanup(oldBuffer);
    }

    public void write(byte[] data, int offset, int length) {
        ensureCapacity(usedBytes + length);
        bufferBuilder.putBytes(data, offset, length);
        usedBytes += length;
    }

    public void reset() {
        usedBytes = 0;
        bufferBuilder.clear();
    }

    private static class MemoryTracker {
        private long totalAllocated = 0;
        private long peakUsage = 0;

        void allocate(long bytes) {
            totalAllocated += bytes;
            peakUsage = Math.max(peakUsage, totalAllocated);
        }

        void deallocate(long bytes) {
            totalAllocated -= bytes;
        }

        long getCurrentUsage() {
            return totalAllocated;
        }

        long getPeakUsage() {
            return peakUsage;
        }
    }
}

Resource Lifecycle Optimization

Generation-Based Cleanup

Use generation-based cleanup to prevent resource leaks:

// Example: Generation-based resource cleanup
public class GenerationBasedResourceManager<T extends AutoCloseable> {
    private final Map<T, Integer> resources = new HashMap<>();
    private final Queue<T> pendingCleanup = new ArrayDeque<>();
    private int currentGeneration = 0;
    private final int maxGenerations;

    public GenerationBasedResourceManager(int maxGenerations) {
        this.maxGenerations = maxGenerations;
    }

    public void addResource(T resource) {
        resources.put(resource, currentGeneration);
    }

    public void advanceGeneration() {
        currentGeneration++;

        // Find resources that need cleanup
        for (Map.Entry<T, Integer> entry : resources.entrySet()) {
            if (currentGeneration - entry.getValue() > maxGenerations) {
                pendingCleanup.offer(entry.getKey());
            }
        }

        // Clean up old resources
        cleanupPendingResources();
    }

    private void cleanupPendingResources() {
        while (!pendingCleanup.isEmpty()) {
            T resource = pendingCleanup.poll();
            resources.remove(resource);

            try {
                resource.close();
            } catch (Exception e) {
                LOGGER.error("Failed to cleanup resource: " + resource, e);
            }
        }
    }

    public void forceCleanupAll() {
        for (T resource : resources.keySet()) {
            try {
                resource.close();
            } catch (Exception e) {
                LOGGER.error("Failed to cleanup resource: " + resource, e);
            }
        }
        resources.clear();
        pendingCleanup.clear();
    }
}

Automatic Resource Management

Implement automatic resource management with reference counting:

// Example: Reference-counted resource manager
public class ReferenceCountedResourceManager<T extends AutoCloseable> {
    private final Map<T, ResourceReference> resources = new ConcurrentHashMap<>();
    private final Map<String, T> resourceCache = new ConcurrentHashMap<>();

    private static class ResourceReference {
        int referenceCount = 1;
        long lastAccessTime;

        ResourceReference() {
            this.lastAccessTime = System.currentTimeMillis();
        }

        void acquire() {
            referenceCount++;
            lastAccessTime = System.currentTimeMillis();
        }

        boolean release() {
            return --referenceCount <= 0;
        }
    }

    public T acquireResource(String key, ResourceFactory<T> factory) {
        T resource = resourceCache.get(key);

        if (resource == null) {
            resource = factory.create();
            resourceCache.put(key, resource);
            resources.put(resource, new ResourceReference());
        } else {
            ResourceReference ref = resources.get(resource);
            if (ref != null) {
                ref.acquire();
            }
        }

        return resource;
    }

    public void releaseResource(T resource) {
        ResourceReference ref = resources.get(resource);
        if (ref != null && ref.release()) {
            // No more references, clean up
            resources.remove(resource);
            resourceCache.values().remove(resource);

            try {
                resource.close();
            } catch (Exception e) {
                LOGGER.error("Failed to cleanup resource: " + resource, e);
            }
        }
    }

    public void cleanupUnusedResources(long maxIdleTime) {
        long currentTime = System.currentTimeMillis();

        Iterator<Map.Entry<T, ResourceReference>> iterator = resources.entrySet().iterator();
        while (iterator.hasNext()) {
            Map.Entry<T, ResourceReference> entry = iterator.next();
            ResourceReference ref = entry.getValue();

            if (ref.referenceCount == 0 &&
                (currentTime - ref.lastAccessTime) > maxIdleTime) {

                T resource = entry.getKey();
                iterator.remove();
                resourceCache.values().remove(resource);

                try {
                    resource.close();
                } catch (Exception e) {
                    LOGGER.error("Failed to cleanup resource: " + resource, e);
                }
            }
        }
    }

    @FunctionalInterface
    public interface ResourceFactory<T> {
        T create();
    }
}

Performance-Optimized Allocation

Tracy Memory Pool Integration

Integrate with Tracy memory pool for performance tracking:

// Example: Tracy memory pool integration
public class TracyMemoryPool {
    private final Map<Integer, Pool> pools = new ConcurrentHashMap<>();
    private final AtomicLong totalAllocations = new AtomicLong();
    private final AtomicLong totalDeallocations = new AtomicLong();

    private static class Pool {
        private final Queue<ByteBuffer> available = new ConcurrentLinkedQueue<>();
        private final int size;
        private final AtomicInteger allocatedCount = new AtomicInteger();
        private final AtomicInteger peakUsage = new AtomicInteger();

        Pool(int size) {
            this.size = size;
        }

        ByteBuffer acquire() {
            ByteBuffer buffer = available.poll();
            if (buffer == null) {
                buffer = ByteBuffer.allocateDirect(size);
                allocatedCount.incrementAndGet();
            }

            peakUsage.updateAndGet(max -> Math.max(max, allocatedCount.get() - available.size()));
            buffer.clear();
            return buffer;
        }

        void release(ByteBuffer buffer) {
            if (buffer.capacity() == size) {
                available.offer(buffer);
            }
        }

        int getAllocatedCount() {
            return allocatedCount.get();
        }

        int getPeakUsage() {
            return peakUsage.get();
        }
    }

    public ByteBuffer allocate(int size) {
        // Round up to nearest power of 2 for pooling efficiency
        int pooledSize = nextPowerOfTwo(size);
        Pool pool = pools.computeIfAbsent(pooledSize, Pool::new);

        totalAllocations.incrementAndGet();
        return pool.acquire();
    }

    public void deallocate(ByteBuffer buffer) {
        Pool pool = pools.get(buffer.capacity());
        if (pool != null) {
            pool.release(buffer);
            totalDeallocations.incrementAndGet();
        }
    }

    public void printPoolStatistics() {
        System.out.println("=== Tracy Memory Pool Statistics ===");
        System.out.printf("Total allocations: %d%n", totalAllocations.get());
        System.out.printf("Total deallocations: %d%n", totalDeallocations.get());
        System.out.printf("Current allocations: %d%n",
                         totalAllocations.get() - totalDeallocations.get());

        pools.forEach((size, pool) -> {
            System.out.printf("Pool %d: allocated=%d, peak=%d%n",
                             size, pool.getAllocatedCount(), pool.getPeakUsage());
        });
    }

    private static int nextPowerOfTwo(int n) {
        return 1 << (32 - Integer.numberOfLeadingZeros(n - 1));
    }
}

Buffer Arena Management

Use buffer arenas to minimize fragmentation:

// Example: Buffer arena management system
public class BufferArenaManager {
    private final List<BufferArena> arenas = new ArrayList<>();
    private final int arenaSize;
    private final int arenaCount;
    private final AtomicInteger currentArenaIndex = new AtomicInteger(0);
    private final ThreadLocal<ByteBuffer> localBuffers = ThreadLocal.withInitial(() -> null);

    private static class BufferArena {
        private final ByteBuffer buffer;
        private final AtomicInteger position = new AtomicInteger(0);
        private final AtomicBoolean inUse = new AtomicBoolean(false);

        BufferArena(int size) {
            this.buffer = ByteBuffer.allocateDirect(size);
        }

        public ByteBuffer allocate(int size) {
            if (inUse.compareAndSet(false, true)) {
                position.set(0);
                return buffer.slice();
            }

            return null; // Arena is in use
        }

        public void release() {
            inUse.set(false);
        }

        public int getRemainingCapacity() {
            return buffer.capacity() - position.get();
        }
    }

    public BufferArenaManager(int arenaSize, int arenaCount) {
        this.arenaSize = arenaSize;
        this.arenaCount = arenaCount;

        for (int i = 0; i < arenaCount; i++) {
            arenas.add(new BufferArena(arenaSize));
        }
    }

    public ByteBuffer allocate(int size) {
        // Try thread-local buffer first
        ByteBuffer localBuffer = localBuffers.get();
        if (localBuffer != null && localBuffer.remaining() >= size) {
            return localBuffer;
        }

        // Find available arena
        for (int i = 0; i < arenaCount; i++) {
            int arenaIndex = (currentArenaIndex.get() + i) % arenaCount;
            BufferArena arena = arenas.get(arenaIndex);

            if (arena.getRemainingCapacity() >= size) {
                ByteBuffer buffer = arena.allocate(size);
                if (buffer != null) {
                    currentArenaIndex.set((arenaIndex + 1) % arenaCount);
                    localBuffers.set(buffer);
                    return buffer;
                }
            }
        }

        // No available arena, allocate direct buffer
        return ByteBuffer.allocateDirect(size);
    }

    public void release(ByteBuffer buffer) {
        // Find and release the arena
        for (BufferArena arena : arenas) {
            if (arena.buffer == buffer) {
                arena.release();
                return;
            }
        }
    }

    public void resetThreadLocal() {
        localBuffers.remove();
    }
}

Memory Leak Prevention

Memory Leak Detection

Implement automatic memory leak detection:

// Example: Memory leak detection system
public class MemoryLeakDetector {
    private final Map<Object, AllocationInfo> allocations = new ConcurrentHashMap<>();
    private final ScheduledExecutorService scheduler =
        Executors.newSingleThreadScheduledExecutor();
    private final long leakDetectionInterval;
    private final long leakThreshold;

    private static class AllocationInfo {
        final long allocationTime;
        final String allocationSite;
        final StackTraceElement[] stackTrace;

        AllocationInfo() {
            this.allocationTime = System.currentTimeMillis();
            this.allocationSite = getAllocationSite();
            this.stackTrace = Thread.currentThread().getStackTrace();
        }

        long getAge() {
            return System.currentTimeMillis() - allocationTime;
        }

        private static String getAllocationSite() {
            StackTraceElement[] stack = Thread.currentThread().getStackTrace();
            // Skip system frames to find user code
            for (int i = 3; i < stack.length; i++) {
                if (!stack[i].getClassName().startsWith(MemoryLeakDetector.class.getName())) {
                    return stack[i].toString();
                }
            }
            return "Unknown";
        }
    }

    public MemoryLeakDetector(long leakDetectionInterval, long leakThreshold) {
        this.leakDetectionInterval = leakDetectionInterval;
        this.leakThreshold = leakThreshold;

        scheduler.scheduleAtFixedRate(this::detectLeaks,
                                    leakDetectionInterval,
                                    leakDetectionInterval,
                                    TimeUnit.MILLISECONDS);
    }

    public void trackAllocation(Object object) {
        allocations.put(object, new AllocationInfo());
    }

    public void trackDeallocation(Object object) {
        allocations.remove(object);
    }

    private void detectLeaks() {
        long currentTime = System.currentTimeMillis();

        allocations.entrySet().removeIf(entry -> {
            AllocationInfo info = entry.getValue();
            long age = currentTime - info.allocationTime;

            if (age > leakThreshold) {
                System.out.printf("Memory leak detected! Age: %dms%n", age);
                System.out.println("Allocation site: " + info.allocationSite);
                System.out.println("Stack trace:");
                for (StackTraceElement element : info.stackTrace) {
                    if (!element.getClassName().startsWith("java.") &&
                        !element.getClassName().startsWith("sun.")) {
                        System.out.println("  " + element);
                    }
                }

                // Remove to avoid spamming
                return true;
            }

            return false;
        });
    }

    public void generateLeakReport() {
        System.out.println("=== Memory Leak Report ===");
        System.out.printf("Active allocations: %d%n", allocations.size());

        allocations.entrySet().stream()
            .sorted((a, b) -> Long.compare(b.getValue().getAge(), a.getValue().getAge()))
            .limit(10) // Top 10 oldest allocations
            .forEach(entry -> {
                AllocationInfo info = entry.getValue();
                System.out.printf("Object %s: age=%dms, site=%s%n",
                                 entry.getKey().getClass().getSimpleName(),
                                 info.getAge(),
                                 info.allocationSite);
            });
    }

    public void shutdown() {
        scheduler.shutdown();
    }
}

Resource Usage Monitoring

Monitor resource usage patterns to identify optimization opportunities:

// Example: Resource usage monitor
public class ResourceUsageMonitor {
    private final Map<String, ResourceMetrics> resourceMetrics = new ConcurrentHashMap<>();
    private final AtomicLong totalMemoryUsed = new AtomicLong();
    private final AtomicLong peakMemoryUsage = new AtomicLong();

    private static class ResourceMetrics {
        private final AtomicLong usageCount = new AtomicLong();
        private final AtomicLong totalSize = new AtomicLong();
        private final AtomicLong peakSize = new AtomicLong();
        private final AtomicLong lastAccessTime = new AtomicLong();

        void recordUsage(long size) {
            usageCount.incrementAndGet();
            totalSize.addAndGet(size);
            peakSize.updateAndGet(max -> Math.max(max, size));
            lastAccessTime.set(System.currentTimeMillis());
        }

        double getAverageSize() {
            long count = usageCount.get();
            return count > 0 ? (double) totalSize.get() / count : 0.0;
        }
    }

    public void recordResourceUsage(String resourceType, long size) {
        resourceMetrics.computeIfAbsent(resourceType, k -> new ResourceMetrics())
            .recordUsage(size);

        long total = totalMemoryUsed.addAndGet(size);
        peakMemoryUsage.updateAndGet(max -> Math.max(max, total));
    }

    public void printUsageReport() {
        System.out.println("=== Resource Usage Report ===");
        System.out.printf("Total memory used: %d bytes%n", totalMemoryUsed.get());
        System.out.printf("Peak memory usage: %d bytes%n", peakMemoryUsage.get());

        resourceMetrics.forEach((type, metrics) -> {
            System.out.printf("%s: count=%d, avg=%.2f, peak=%d%n",
                             type,
                             metrics.usageCount.get(),
                             metrics.getAverageSize(),
                             metrics.peakSize.get());
        });

        // Identify resource types with high variance
        resourceMetrics.entrySet().stream()
            .filter(entry -> entry.getValue().getAverageSize() > 0)
            .map(entry -> new Object[]{entry.getKey(), entry.getValue()})
            .sorted((a, b) -> Double.compare(
                ((ResourceMetrics) b[1]).peakSize.get() / ((ResourceMetrics) b[1]).getAverageSize(),
                ((ResourceMetrics) a[1]).peakSize.get() / ((ResourceMetrics) a[1]).getAverageSize()
            ))
            .limit(5)
            .forEach(entry -> {
                String type = (String) entry[0];
                ResourceMetrics metrics = (ResourceMetrics) entry[1];
                double varianceRatio = (double) metrics.peakSize.get() / metrics.getAverageSize();

                if (varianceRatio > 10.0) {
                    System.out.printf("Warning: %s has high size variance (%.2fx)%n",
                                     type, varianceRatio);
                }
            });
    }
}

Best Practices

Memory Management Guidelines

1. Pool frequently used resources to reduce allocation overhead
2. Use generation-based cleanup to prevent resource leaks
3. Monitor memory usage to identify optimization opportunities
4. Implement automatic cleanup for long-running applications
5. Profile memory patterns before optimizing

Performance Considerations

// ❌ WRONG - Frequent allocations in hot path
public void renderInefficient() {
    for (Object object : objects) {
        ByteBuffer buffer = ByteBuffer.allocateDirect(1024); // New allocation each frame!
        processObject(object, buffer);
    }
}

// ✅ CORRECT - Use buffer pooling
public void renderEfficient() {
    ByteBuffer buffer = bufferPool.acquire(1024);
    try {
        for (Object object : objects) {
            buffer.clear();
            processObject(object, buffer);
        }
    } finally {
        bufferPool.release(buffer);
    }
}

Common Pitfalls

1. Resource Leaks: Forgetting to release GPU resources
2. Memory Fragmentation: Excessive small allocations
3. Over-pooling: Keeping too many resources in pools
4. Thread Contention: Poor synchronization in resource managers
5. Hot Path Allocations: Creating objects in rendering loops

Next Steps

• Custom Entity Renderer Example - Practical memory management in action
• Shader Integration Example - Advanced resource lifecycle management
• Performance Optimization - Comprehensive performance guide

Common Issues

1. Buffer Overflows: Always check buffer capacity before writing
2. Resource Contention: Use proper synchronization for shared resources
3. Memory Bloat: Monitor and limit pool sizes
4. GPU Memory Limits: Be aware of VRAM constraints
5. Cleanup Timing: Ensure proper cleanup order for dependent resources