A life cycled buffer of memory, with separate reader and writer offsets.

A buffer is a logically sequential stretch of memory with a certain capacity, an offset for writing, and an offset for reading. Buffers may be composed of multiple components, where each component is a guaranteed contiguous chunk of memory.

Creating a buffer

Buffers are created by allocators, and their allocate family of methods. A number of standard allocators exist, and are available through static methods on the BufferAllocator interface.

Buffer life cycle

The buffer has a life cycle, where it is allocated, used, and deallocated. When the buffer is initially allocated, a pairing close() call will deallocate it. If a buffer is sent elsewhere, the close method on the given instance will become a no-op. The buffer can be thought of as a view onto memory, and calling send() on the buffer will effectively close that view, and recreate it upon reception at its destination.

Thread-safety

Buffers are not thread-safe.

Accessing data

Data access methods fall into two classes:

1. Access that are based on, and updates, the read or write offset positions.
• These accessor methods are typically called readX or writeX.
2. Access that take offsets as arguments, and do not update read or write offset positions.
• These accessor methods are typically called getX or setX.

A buffer contains two mutable offset positions: one for reading and one for writing. These positions use zero-based indexing, such that the first byte of data in the buffer is placed at offset 0, and the last byte in the buffer is at offset capacity - 1. The readerOffset() is the offset into the buffer from which the next read will take place, and is initially zero. The reader offset must always be less than or equal to the writerOffset(). The writerOffset() is likewise the offset into the buffer where the next write will take place. The writer offset is also initially zero, and must be less than or equal to the capacity.

This carves the buffer into three regions, as demonstrated by this diagram:

     +-------------------+------------------+------------------+
     | discardable bytes |  readable bytes  |  writable bytes  |
     |                   |     (CONTENT)    |                  |
     +-------------------+------------------+------------------+
     |                   |                  |                  |
     0      <=     readerOffset  <=   writerOffset    <=    capacity

Byte Order

Buffers are always big endian, and this cannot be changed. Usages that need to get, set, read, or write, little-endian values will have to flip the byte order of the values they read and write.

Splitting buffers

The split() method breaks a buffer into two. The two buffers will share the underlying memory, but their regions will not overlap, ensuring that the memory is safely shared between the two.

Splitting a buffer is useful for when you want to hand over a region of a buffer to some other, perhaps unknown, piece of code, and relinquish your ownership of that buffer region in the process. Examples include aggregating messages into an accumulator buffer, and sending messages down the pipeline for further processing, as split buffer regions, once their data has been received in its entirety. If you instead wish to temporarily share a region of a buffer, you will have to pass offset and length along with the buffer, or you will have to make a copy of the region.

Buffers as constants

Sometimes, the same bit of data will be processed or transmitted over and over again. In such cases, it can be tempting to allocate and fill a buffer once, and then reuse it. Such reuse must be done carefully, however, to avoid a number of bugs. The BufferAllocator has a BufferAllocator#constBufferSupplier(byte[]) method that solves this, and prevents these bugs from occurring.