Unlocking Netty’s ByteBuf: How Pooled Off‑Heap Memory Allocation Works

Explanation

When learning Netty, ByteBuf appears everywhere, but efficiently allocating ByteBuf is complex. This article explains the details of Netty’s pooled off‑heap memory allocation.

ByteBuf Importance

ByteBuf is the data container in Netty; efficient allocation is crucial.

Netty reads data from a socket, prepares to write data to a socket, and checks whether the buffer is off‑heap; if not, it constructs a direct buffer.

if (msg instanceof ByteBuf) {
    ByteBuf buf = (ByteBuf) msg;
    if (buf.isDirect()) {
        return msg;
    }
    return newDirectBuffer(buf);
}

Overview

The focus is on pooled memory allocation; PooledByteBufAllocator is the entry point.

When sending data, Netty checks if the buffer is off‑heap; if not, it wraps the data in a direct buffer.

Operation Entry Class

Initialization of PooledByteBufAllocator :

The core allocation theory is based on jemalloc , a Java implementation of the jemalloc algorithm.

PoolThreadCache

The cache starts empty; freed buffers are placed into the cache queues for reuse.

PoolArena

PoolArena contains PoolChunkList and PoolSubpage . A default Chunk is 16 MiB, represented as a complete binary tree with 4096 nodes (2048 leaves, each leaf = 8 KiB page).

In Java the binary tree is stored in an array indexed from 1.

The depthMap array records the depth of each node; a value of 0 means a 16 MiB allocation is possible, 1 means 8 MiB, …, 11 means 8 KiB, and 12 indicates the node is fully allocated.

PoolChunk

The tree structure is visualized in the diagram.

SubpagePool

Subpages are divided into tinySubpagePools and smallSubpagePools . For example, allocating 256 B within an 8 KiB page yields 32 slots, tracked by a bitmap: private final long[] bitmap; Each bit represents a slot (1 = used, 0 = free).

Allocation Core

Entry: ByteBuf byteBuf = alloc.directBuffer(256); The allocation proceeds through newByteBuf(maxCapacity), which uses Netty’s Recycler pool to obtain a PooledByteBuf instance.

Step 1: Try to allocate from the appropriate cache; if successful, return.

Step 2: If step 1 fails, determine whether a page or subpage is needed, locate the corresponding pool, and allocate from existing chunks or create a new chunk.

Release Core

Release entry: byteBuf.release(); The buffer is returned to the appropriate cache queue for future reuse.

The buffer is cached in the corresponding PoolThreadCache queue.