NIO's ByteBuffer sits between a channel and the application. The channel handles network I/O and connection events, but the buffer is what actually carries bytes during transfer. It acts as a temporary staging area for I/O data and allows bulk reads and writes to improve efficiency. NIO provides typed buffers such as ByteBuffer, CharBuffer, ShortBuffer, IntBuffer, LongBuffer, FloatBuffer, and DoubleBuffer; for network transport, bytes are the basic unit, so ByteBuffer is the byte container. Its implementation, however, is more cumbersome than Netty wanted, which is why Netty introduced ByteBuf. The source-level design of ByteBuf is the focus here.
ByteBuffer Revisited
Every NIO buffer has four core properties: capacity, limit, position, and mark, with the invariant mark <= position <= limit <= capacity.
capacity</td>
<td>Maximum amount of data the buffer can hold. It is set when the buffer is created and cannot change.</td>
</tr>
<tr>
<td>limit</td>
<td>Current boundary of the buffer. Reads and writes cannot go beyond it, but the limit itself can be changed.</td>
</tr>
<tr>
<td>position</td>
<td>Index of the next element to be read or written. It changes after each read or write.</td>
</tr>
<tr>
<td>mark</td>
<td>A saved position. Calling mark() sets mark = position; reset() restores position to the mark.</td>
</tr>
</tbody>
</table>
ByteBuffer is abstract and cannot be instantiated directly. Its static factory methods are the usual entry points:
allocateDirect(int capacity)creates a buffer using operating-system memory rather than the JVM heap. It can couple better with the OS and may improve I/O speed, but direct allocation is expensive. It makes sense for large, long-lived buffers or buffers that are reused frequently.allocate(int capacity)creates a heap buffer backed by a byte array of the given capacity.wrap(byte[] array)wraps an existing byte array. The buffer and the array share data, so changes in either are visible in the other. Underneath,ByteBufferis backed by a byte array anyway;allocatesimply creates that array for you.wrap(byte[] array, int offset, int length)wraps an array with an explicit offset and length. The offset becomes the buffer'sposition, and the limit becomesoffset + length.
The common methods are mostly about moving those four properties:
limit()andlimit(10)read or set the limit. All four basic properties have similar getter/setter pairs.reset()setspositionback tomark.clear()setsposition = 0,limit = capacity, andmark = -1. It resets the cursor state but does not erase the underlying data.flip()setslimit = position,position = 0, andmark = -1. It turns a buffer that was being written into one ready to be read.rewind()setsposition = 0andmark = -1, leaving the limit unchanged. It rewinds to the beginning without changing the readable range.remaining()returnslimit - position;hasRemaining()returns whetherposition < limit.compact()moves the unread bytes betweenpositionandlimitto the front, then setsposition = limit - positionandlimit = capacity. Ifpositionis first moved tolimit,compact()becomes equivalent toclear().get()performs a relative read: it reads one byte atpositionand incrementsposition.get(int index)performs an absolute read atindexwithout changingposition.get(byte[] dst, int offset, int length)readslengthbytes starting atpositioninto the destination array.put(byte b)performs a relative write atpositionand incrementsposition.put(int index, byte b)performs an absolute write atindexwithout changingposition.
Why Netty Needed a Different Byte Container
NIO's ByteBuffer has a single position pointer. Switching between reading and writing requires manual calls to flip() or rewind() to adjust position. Its capacity is fixed at allocation time; it cannot grow or shrink. If a value larger than the remaining capacity must be written, the operation fails, and code has to validate writable space before each write.
Netty's AbstractByteBuf separates the read and write pointers and expands automatically during writes. From the caller's perspective, the underlying mechanics are hidden, operations are simpler, and there is less defensive code. NIO's duplicate() can copy a buffer object while sharing the same memory and maintaining an independent position; Netty's ByteBuf adopts the same idea and adds a memory pool. The pool consists of memory blocks of a certain size and count, with a default block size of 16 MB. When data is read from a channel, Netty does not need to allocate a fresh ByteBuf every time; it can share a slice of a larger block, initialize its size, and maintain independent read/write pointers.
Netty also uses reference counting, so buffers must be released manually. Every time a ByteBuf is duplicated or a new buffer is derived from it, the reference count must be increased.

AbstractByteBuf
AbstractByteBuf is the subclass that defines common state such as the reader index, writer index, mark, and maximum capacity. It implements a template for read and write operations, while the actual byte access is left to subclasses. This split keeps the public behavior consistent across heap buffers, direct buffers, pooled buffers, and composite buffers.

The writeBytes() path involves expansion. Besides validating the operation, it must calculate a new capacity. If the buffer size is a power of two, subclasses can allocate memory more conveniently, so the expanded size is rounded to a power of two.
The readBytes() path calls getBytes() starting at the current reader index and copies length bytes into the destination byte array. Different subclasses perform the copy differently, so getBytes() remains abstract in AbstractByteBuf. PooledHeapByteBuf and PooledDirectByteBuf provide their own implementations for heap and direct memory respectively.
Reference Counting and Lifecycle Management
Netty uses off-heap memory for I/O reads and writes to achieve zero copy, but direct buffers are much slower to allocate and reclaim than ordinary JVM heap objects. Reference counting is how Netty manages buffer ownership and release. Combined with pooling, Netty can allocate a large memory region once and reuse it repeatedly. When reading from a SocketChannel, for example, Netty carves out a small portion of a larger block. Because that small buffer shares memory with the larger block, the larger block's reference count is increased. When the small buffer is no longer needed, it is returned to the block and the reference count is decreased.
Most ByteBuf implementations that use reference counting inherit from AbstractReferenceCountedByteBuf, which has a refCnt property at its center. Because a ByteBuf may be used concurrently, refCnt is declared volatile for visibility. Netty creates a large number of ByteBuf instances, so it updates refCnt through AtomicIntegerFieldUpdater rather than using an AtomicInteger field. An AtomicInteger object carries an object header of roughly 16 bytes; across hundreds of thousands or millions of buffers, using the updater can save tens or hundreds of megabytes.

In older versions, refCnt started at 1, incremented or decremented by 1 on each operation, and a value greater than 0 meant the buffer was still usable while 0 meant it had been released. In Netty v4.1.38.Final, the initial value is 2 and the update logic changed, which is why the updater deserves a closer look.
ReferenceCountUpdater
ReferenceCountUpdater is the helper that performs reference-count operations for AbstractReferenceCountedByteBuf. Compared with older Netty versions, v4.1.38.Final uses an optimistic-lock style: it modifies the count first and validates afterward. For example, retain() increments refCnt, and if an overflow occurs, it rolls back and throws an exception. Older versions used atomic operations with repeated pre-checks and compareAndSet attempts. The newer approach improves throughput under contention, but if the old scheme of starting at 1 and adding or subtracting 1 were kept, it would create edge cases. That is why the reference-count design was reworked.

Buffers derived through duplicate() or slice() share the underlying buffer with the original object. The original object's reference may need to be increased, and retain0() is the method that performs the increase.
retain()
retain0() implements the details behind retain(). The update does not check for overflow before modifying the count; it modifies first and checks afterward, rolling back if the count overflowed. Under high concurrency this improves throughput compared with the older approach. The count is not always simply plus one or minus one because a pre-modification check cannot be reliable without locking: another thread may change the value between the check and the update. Checking in a loop after an overflow is also not useful once the overflow has already happened.
release()
Concurrent calls can expose a subtle problem. Suppose thread 1 calls release(), thread 2 calls retain(), and thread 3 calls release() at the same time. Without care, the ByteBuf could be destroyed more than once. Netty handles this by using odd and even values to represent different states: an odd count indicates a destroyed state, while an even count indicates a normal state. After the final release, the count becomes odd. When a ByteBuf is finished, release() returns true or false; false means references remain, while true means no references remain and deallocate() is called to destroy the buffer.
ReferenceCountUpdater relies mainly on JDK CAS to modify the counter. To improve performance, it also uses Unsafe for direct memory operations.
CompositeByteBuf
CompositeByteBuf combines multiple ByteBuf instances and presents a unified readerIndex and writerIndex. It does not copy the underlying data; it assembles the buffers into a single logical view. That makes it another form of zero copy in Netty, and it is especially useful in encoding and decoding.

For example, a message header and message body may live in two separate ByteBuf instances. Before writing them into a channel outbound buffer, the encoder may need the total message length. Combining the two buffers into one logical view avoids extra processing to calculate the overall length. During decoding, TCP can produce sticky packets and half packets, so a container that can accumulate partial bytes is useful. CompositeByteBuf fits that role and avoids an extra data copy each time bytes are read from a socket. Netty's ByteToMessageDecoder does not use CompositeByteBuf by default in its Cumulator; a subclass can call setCumulator to change that. The choice depends on the scenario, because CompositeByteBuf uses more complex logic and can be slower than a straightforward memory copy.
Internally, CompositeByteBuf maintains a collection of Component objects. A Component wraps a ByteBuf and tracks its position and offset within the composite structure. External operations appear to act on the CompositeByteBuf, but the actual work is delegated to the buffers inside the components.

Basic Structure and Properties
The two key properties are the component array and the component count. The Component array is what turns several buffers into one logical buffer and avoids copying between them. Each component stores the buffer plus the indexing and offset information needed to map composite reads and writes onto the underlying buffer.
addComponent()
addComponent() ultimately calls addComponent0(). That method unwraps the incoming ByteBuf, creates a Component from its reader index, readable length, and offset, and adds it to the components array. If the array needs to grow or the insertion point is not at the end, existing components may have to move.
newComponent() first reads the source buffer's reader index and readable length, unwraps the buffer, obtains the unwrapped reader index, and then creates the Component.
addComp() inserts the component at the appropriate position. By default that position is componentCount, meaning the end of the array.
shiftComps() handles insertion in the middle or at the end and may trigger expansion. If expansion is needed, the array grows to roughly 1.5 times its old size. When inserting at the end, the old elements can be copied directly into the new array. When inserting in the middle, elements before and after the insertion point are copied into their new positions so that a slot is left open. If no expansion is needed and the insertion is not at the end, the element at the insertion point and all following elements are shifted back to make room.
These array copies are shallow copies using Arrays.copyOf and System.arraycopy; only references are copied.




updateComponentOffsets() recalculates offsets after an insertion in the middle when there is readable data. Components after the insertion point have effectively been moved back, so their offsets must be updated.

consolidateIfNeeded() performs a merge when the number of components exceeds the maximum allowed count, which defaults to 16. consolidate0() calculates the readable bytes of the components, creates a new buffer, walks the components being merged, transfers their contents into the new buffer, removes the old components from the array, wraps the new buffer as a new component, adds it back, and updates the offsets.
removeComponent()
Removal is simpler than insertion because there is no need to grow the array. The target element is deleted, the remaining array is compacted, and the indexes are updated.
discardReadComponents()
discardReadComponents() removes bytes that have already been read from the composite buffer, trimming components whose readable range has been consumed.
PooledByteBuf
PooledByteBuf is an important abstract class that extends AbstractReferenceCountedByteBuf. Its instances are created mainly by PooledByteBufAllocator. There are two common implementations: PooledDirectByteBuf, based on a direct memory pool and used by default for Netty I/O because off-heap memory can reduce data copies, and PooledHeapByteBuf, based on a heap memory pool.
Creating a PooledByteBuf is expensive, and high-concurrency network I/O can create many instances. Netty pools buffer objects to reduce that cost and reuse buffers. A pooled buffer therefore carries memory-pool metadata: the chunk it belongs to, its position within that chunk, and its size. It also records the memory, handler, and related state during initialization.

Initialization is straightforward: because the buffer comes from a pool, it must record which chunk and which portion of cache space it owns. That is why fields such as chunk, memory, and handler appear. The same structure supports reading data from a channel, writing data to a channel, automatic expansion when capacity is exceeded, and recycling when the object is no longer used. The pooling details and memory allocation strategy are a larger topic, but the key point is that PooledByteBuf combines reference counting with pooled memory rather than allocating and freeing a fresh buffer for every I/O operation.