The CompositeBuffer is a concrete Buffer implementation that make a number of other buffers appear as one. A composite buffer behaves the same as a normal, non-composite buffer in every way, so you normally don't need to handle them specially.

A composite buffer is constructed using one of the compose methods:

• BufferAllocator#compose(Iterable) creates a composite buffer from the buffers that are sent to it via the passed in send objects. Since Send#receive() transfers ownership, the resulting composite buffer will have ownership, because it is guaranteed that there are no other references to its constituent buffers.
• BufferAllocator#compose(Send) creates a composite buffer with a single component. Since Send#receive() transfers ownership, the resulting composite buffer will have ownership, because it is guaranteed that there are no other references to its constituent buffer.
• BufferAllocator#compose() creates an empty, zero capacity, composite buffer. Such empty buffers may change their read-only states when they gain their first component.

Composite buffers can later be extended with internally allocated components, with ensureWritable(int), or with externally allocated buffers, using extendWith(Send).

How buffers compose

A buffer can be thought of as having three distinct regions, in order:

1. Memory that have been read.
2. Memory that is readable.
3. Memory that can be written to.

A composite buffer must present itself similarly, but may be composed of buffers where their offsets don't line up, and thus end up producing "gaps" in the composite buffer. The solution is that the composite buffer hide these gaps from view.

For example, if we compose two buffers that both have non-zero read-offset, then the composite buffer will get the read-offset of the first buffer, followed by a concatenation of the readable memory from both. Similarly, the write-offset of the composite buffer will come from the last buffer with a non-zero write-offset, and any writable memory prior to the last readable memory region will be hidden:

    First buffer                Second buffer
     +----------------------+    +--------------------+
    0|    |r/o      |w/o    |   0|    |r/o     |w/o   |
     +----+---------+-------+    +----+--------+------+
      \    \         \  ,____________/   ,___________/
       \    \         \/                /
        +----+---------+--------+------+
       0|    |r/o      :        |w/o   |  Composite buffer
        +------------------------------+

Components in the middle can have both their end-regions hidden in the same way, so only their readable memory is included in the composite buffer. Buffers that consist entirely of memory that has already been read, or memory that is writable, can also concatenate onto those regions at the ends. The final capacity of the composite buffer, will be the sum of all the visible regions.

Reads and writes to the composite buffer that modifies the read or write offsets, will also modify the relevant offsets in the constituent buffers.

Constituent buffer requirements

The buffers that are being composed must all have the same writability. Either all components must be read-only, or they must all be writable.

It is not a requirement that the buffers have the same size.

It is not a requirement that the buffers are allocated by this allocator, but if Buffer#ensureWritable(int) is called on the composed buffer, and the composed buffer needs to be expanded, then this allocator instance will be used for allocation the extra memory.

Ownership and Send

Sending a composite buffer implies sending all of its constituent buffers. For sending to be possible, both the composite buffer itself, and all of its constituent buffers, must be in a state that permits them being sent. This should be the case by default, as it shouldn't be possible to create composite buffers that can't be sent.