Module io.netty5.buffer
Package io.netty5.buffer.api

Interface CompositeBuffer

  • All Superinterfaces:
    AutoCloseable, Buffer, BufferAccessor, Resource<Buffer>
    public interface CompositeBuffer
extends Buffer
    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.

    • Method Detail

      • compose

        static CompositeBuffer compose​(BufferAllocator allocator)
        Create an empty composite buffer, that has no components. The buffer can be extended with components using either ensureWritable(int) or extendWith(Send).
        Parameters:
        allocator - The allocator for the composite buffer. This allocator will be used e.g. to service ensureWritable(int) calls.
        Returns:
        A composite buffer that has no components, and has a capacity of zero.

      • extendWith

        CompositeBuffer extendWith​(Send<Buffer> extension)
        Extend this composite buffer with the given extension buffer. This works as if the extension had originally been included at the end of the list of constituent buffers when the composite buffer was created. The extension buffer is added to the end of this composite buffer, which is modified in-place.
        Parameters:
        extension - The buffer to extend the composite buffer with.
        Returns:
        This composite buffer instance.
        See Also:
        BufferAllocator.compose(Send)

      • splitComponentsFloor

        CompositeBuffer splitComponentsFloor​(int splitOffset)
        Split this buffer at a component boundary that is less than or equal to the given offset.

        This method behaves the same as split(int), except no components are split.

        Parameters:
        splitOffset - The maximum split offset. The real split offset will be at a component boundary that is less than or equal to this offset.
        Returns:
        A new buffer with independent and exclusive ownership over the bytes from the beginning to a component boundary less than or equal to the given offset of this buffer.

      • splitComponentsCeil

        CompositeBuffer splitComponentsCeil​(int splitOffset)
        Split this buffer at a component boundary that is greater than or equal to the given offset.

        This method behaves the same as split(int), except no components are split.

        Parameters:
        splitOffset - The minimum split offset. The real split offset will be at a component boundary that is greater than or equal to this offset.
        Returns:
        A new buffer with independent and exclusive ownership over the bytes from the beginning to a component boundary greater than or equal to the given offset of this buffer.

      • decomposeBuffer

        Buffer[] decomposeBuffer()
        Break a composite buffer into its constituent components.

        This "consumes" the composite buffer, leaving the composite buffer instance as if it had been closed. The buffers in the returned array are not closed, and become owned by the caller.

        Returns:
        An array of the constituent buffer components.

      • readerOffset

        CompositeBuffer readerOffset​(int offset)
        Description copied from interface: Buffer
        Set the reader offset. Make the next read happen from the given offset into the buffer.
        Specified by:
        readerOffset in interface Buffer
        Parameters:
        offset - The reader offset to set.
        Returns:
        This Buffer.

      • writerOffset

        CompositeBuffer writerOffset​(int offset)
        Description copied from interface: Buffer
        Set the writer offset. Make the next write happen at the given offset.
        Specified by:
        writerOffset in interface Buffer
        Parameters:
        offset - The writer offset to set.
        Returns:
        This Buffer.

      • skipReadableBytes

        default CompositeBuffer skipReadableBytes​(int delta)
        Description copied from interface: Buffer
        Move the reader offset forward by the given delta.
        Specified by:
        skipReadableBytes in interface Buffer
        Parameters:
        delta - to accumulate.
        Returns:
        This buffer instance.

      • skipWritableBytes

        default CompositeBuffer skipWritableBytes​(int delta)
        Description copied from interface: Buffer
        Move the writer offset to ahead by the given delta.
        Specified by:
        skipWritableBytes in interface Buffer
        Parameters:
        delta - to accumulate.
        Returns:
        This buffer instance.

      • makeReadOnly

        CompositeBuffer makeReadOnly()
        Description copied from interface: Buffer
        Makes this buffer read-only. This is irreversible. This operation is also idempotent, so calling this method multiple times on the same buffer makes no difference.
        Specified by:
        makeReadOnly in interface Buffer
        Returns:
        This buffer instance.

      • writeBytes

        default CompositeBuffer writeBytes​(Buffer source)
        Description copied from interface: Buffer
        Writes into this buffer, all the readable bytes from the given buffer. This updates the write offset of this buffer, and the reader offset of the given buffer.
        Specified by:
        writeBytes in interface Buffer
        Parameters:
        source - The buffer to read from.
        Returns:
        This buffer.

      • writeBytes

        default CompositeBuffer writeBytes​(byte[] source)
        Description copied from interface: Buffer
        Writes into this buffer, all the bytes from the given byte array. This updates the write offset of this buffer by the length of the array.
        Specified by:
        writeBytes in interface Buffer
        Parameters:
        source - The byte array to read from.
        Returns:
        This buffer.

      • writeBytes

        default CompositeBuffer writeBytes​(byte[] source,
                                   int srcPos,
                                   int length)
        Description copied from interface: Buffer
        Writes into this buffer, the given number of bytes from the byte array. This updates the write offset of this buffer by the length argument.
        Specified by:
        writeBytes in interface Buffer
        Parameters:
        source - The byte array to read from.
        srcPos - Position in the source from where bytes should be written to this buffer.
        length - The number of bytes to copy.
        Returns:
        This buffer.

      • readBytes

        default CompositeBuffer readBytes​(byte[] destination,
                                  int destPos,
                                  int length)
        Description copied from interface: Buffer
        Read from this buffer, into the destination array, the given number of bytes. This updates the read offset of this buffer by the length argument.
        Specified by:
        readBytes in interface Buffer
        Parameters:
        destination - The byte array to write into.
        destPos - Position in the destination to where bytes should be written from this buffer.
        length - The number of bytes to copy.
        Returns:
        This buffer.

      • writeBoolean

        default CompositeBuffer writeBoolean​(boolean value)
        Description copied from interface: BufferAccessor
        Write the given boolean value at the current Buffer.writerOffset(), and increase the writer offset by Byte.BYTES. A boolean gets written as a byte to this buffer. All byte values which are not equal to zero are considered as the boolean value true, zero represents false.
        Specified by:
        writeBoolean in interface BufferAccessor
        Parameters:
        value - The boolean value to write.
        Returns:
        This Buffer.

      • setBoolean

        default CompositeBuffer setBoolean​(int woff,
                                   boolean value)
        Description copied from interface: BufferAccessor
        Set the given boolean value at the given write offset. The Buffer.writerOffset() is not modified. A boolean gets written as a byte to this buffer. All byte values which are not equal to zero are considered as the boolean value true, zero represents false.
        Specified by:
        setBoolean in interface BufferAccessor
        Parameters:
        woff - The write offset, an absolute offset into this buffer to write to.
        value - The boolean value to write.
        Returns:
        This Buffer.

      • readBytes

        default CompositeBuffer readBytes​(ByteBuffer destination)
        Description copied from interface: Buffer
        Read from this buffer, into the destination ByteBuffer This updates the read offset of this buffer and also the position of the destination ByteBuffer.

        Note: the behaviour is undefined if the given ByteBuffer is an alias for the memory in this buffer.

        Specified by:
        readBytes in interface Buffer
        Parameters:
        destination - The ByteBuffer to write into.
        Returns:
        This buffer.

      • ensureWritable

        default CompositeBuffer ensureWritable​(int size)
        Description copied from interface: Buffer
        Ensures that this buffer has at least the given number of bytes of available space for writing. If this buffer already has the necessary space, then this method returns immediately. If this buffer does not already have the necessary space, then it will be expanded using the BufferAllocator the buffer was created with. This method is the same as calling Buffer.ensureWritable(int, int, boolean) where allowCompaction is true.
        Specified by:
        ensureWritable in interface Buffer
        Parameters:
        size - The requested number of bytes of space that should be available for writing.
        Returns:
        This buffer instance.

      • ensureWritable

        CompositeBuffer ensureWritable​(int size,
                               int minimumGrowth,
                               boolean allowCompaction)
        Description copied from interface: Buffer
        Ensures that this buffer has at least the given number of bytes of available space for writing. If this buffer already has the necessary space, then this method returns immediately. If this buffer does not already have the necessary space, then space will be made available in one or all of the following available ways:
        • If allowCompaction is true, and sum of the read and writable bytes would be enough to satisfy the request, and it (depending on the buffer implementation) seems faster and easier to compact the existing buffer rather than allocation a new buffer, then the requested bytes will be made available that way. The compaction will not necessarily work the same way as the Buffer.compact() method, as the implementation may be able to make the requested bytes available with less effort than is strictly mandated by the Buffer.compact() method.
        • Regardless of the value of the allowCompaction, the implementation may make more space available by just allocating more or larger buffers. This allocation would use the same BufferAllocator that this buffer was created with.
        • If allowCompaction is true, then the implementation may choose to do a combination of compaction and allocation.
        Specified by:
        ensureWritable in interface Buffer
        Parameters:
        size - The requested number of bytes of space that should be available for writing.
        minimumGrowth - The minimum number of bytes to grow by. If it is determined that memory should be allocated and copied, make sure that the new memory allocation is bigger than the old one by at least this many bytes. This way, the buffer can grow by more than what is immediately necessary, thus amortising the costs of allocating and copying.
        allowCompaction - true if the method is allowed to modify the reader offset and writer offset, otherwise false.
        Returns:
        This buffer instance.

      • copy

        default CompositeBuffer copy()
        Description copied from interface: Buffer
        Returns a copy of this buffer's readable bytes. Modifying the content of the returned buffer will not affect this buffers contents. The two buffers will maintain separate offsets. This method is identical to buf.copy(buf.readerOffset(), buf.readableBytes()). This method does not modify Buffer.readerOffset() or Buffer.writerOffset() of this buffer.

        The copy is created with a write offset equal to the length of the copied data, so that the entire contents of the copy is ready to be read.

        The returned buffer will not be read-only, regardless of the read-only state of this buffer.

        Specified by:
        copy in interface Buffer
        Returns:
        A new buffer instance, with independent Buffer.readerOffset() and Buffer.writerOffset(), that contains a copy of the readable region of this buffer.

      • copy

        default CompositeBuffer copy​(int offset,
                             int length)
        Description copied from interface: Buffer
        Returns a copy of the given region of this buffer. Modifying the content of the returned buffer will not affect this buffers contents. The two buffers will maintain separate offsets. This method does not modify Buffer.readerOffset() or Buffer.writerOffset() of this buffer.

        The copy is created with a write offset equal to the length of the copy, so that the entire contents of the copy is ready to be read.

        The returned buffer will not be read-only, regardless of the read-only state of this buffer. This has the same effect as calling Buffer.copy(int, int, boolean) with a false read-only argument.

        Specified by:
        copy in interface Buffer
        Parameters:
        offset - The offset where copying should start from. This is the offset of the first byte copied.
        length - The number of bytes to copy, and the capacity of the returned buffer.
        Returns:
        A new buffer instance, with independent Buffer.readerOffset() and Buffer.writerOffset(), that contains a copy of the given region of this buffer.

      • copy

        CompositeBuffer copy​(int offset,
                     int length,
                     boolean readOnly)
        Description copied from interface: Buffer
        Returns a copy of the given region of this buffer. Modifying the content of the returned buffer will not affect this buffers contents. The two buffers will maintain separate offsets. This method does not modify Buffer.readerOffset() or Buffer.writerOffset() of this buffer.

        The copy is created with a write offset equal to the length of the copy, so that the entire contents of the copy is ready to be read.

        The returned buffer will be read-only if, and only if, the readOnly argument is true, and it will not be read-only if the argument is false. This is the case regardless of the read-only state of this buffer.

        If this buffer is read-only, and a read-only copy is requested, then implementations may use structural sharing and have both buffers backed by the same underlying memory.

        Specified by:
        copy in interface Buffer
        Parameters:
        offset - The offset where copying should start from. This is the offset of the first byte copied.
        length - The number of bytes to copy, and the capacity of the returned buffer.
        readOnly - The desired Buffer.readOnly() state of the returned buffer.
        Returns:
        A new buffer instance, with independent Buffer.readerOffset() and Buffer.writerOffset(), that contains a copy of the given region of this buffer.

      • split

        default CompositeBuffer split()
        Description copied from interface: Buffer
        Splits the buffer into two, at the write offset position.

        The region of this buffer that contain the previously read and readable bytes, will be captured and returned in a new buffer, that will hold its own ownership of that region. This allows the returned buffer to be independently sent to other threads.

        The returned buffer will adopt the Buffer.readerOffset() of this buffer, and have its Buffer.writerOffset() and Buffer.capacity() both set to the equal to the write-offset of this buffer.

        The memory region in the returned buffer will become inaccessible through this buffer. This buffer will have its capacity reduced by the capacity of the returned buffer, and the read and write offsets of this buffer will both become zero, even though their position in memory remain unchanged.

        Effectively, the following transformation takes place: 

        
         This buffer:
          +------------------------------------------+
         0|   |r/o                  |w/o             |cap
          +---+---------------------+----------------+
         /   /                     / \               \
        /   /                     /   \               \
       /   /                     /     \               \
      /   /                     /       \               \
     /   /                     /         \               \
    +---+---------------------+           +---------------+
    |   |r/o                  |w/o & cap  |r/o & w/o      |cap
    +---+---------------------+           +---------------+
    Returned buffer.                      This buffer.
        When the buffers are in this state, both of the split parts retain an atomic reference count on the underlying memory. This means that shared underlying memory will not be deallocated or returned to a pool, until all the split parts have been closed.

        Composite buffers have it a little easier, in that at most only one of the constituent buffers will actually be split. If the split point lands perfectly between two constituent buffers, then a composite buffer can simply split its internal array in two.

        Split buffers support all operations that normal buffers do, including Buffer.ensureWritable(int).

        See the Splitting buffers section for details.

        Specified by:
        split in interface Buffer
        Returns:
        A new buffer with independent and exclusive ownership over the previously read and readable bytes from this buffer.

      • split

        CompositeBuffer split​(int splitOffset)
        Description copied from interface: Buffer
        Splits the buffer into two, at the given splitOffset.

        The region of this buffer that precede the splitOffset, will be captured and returned in a new buffer, that will hold its own ownership of that region. This allows the returned buffer to be independently sent to other threads.

        The returned buffer will adopt the Buffer.readerOffset() and Buffer.writerOffset() of this buffer, but truncated to fit within the capacity dictated by the splitOffset.

        The memory region in the returned buffer will become inaccessible through this buffer. If the Buffer.readerOffset() or Buffer.writerOffset() of this buffer lie prior to the splitOffset, then those offsets will be moved forward, so they land on offset 0 after the split.

        Effectively, the following transformation takes place: 

        
         This buffer:
          +--------------------------------+
         0|               |splitOffset     |cap
          +---------------+----------------+
         /               / \               \
        /               /   \               \
       /               /     \               \
      /               /       \               \
     /               /         \               \
    +---------------+           +---------------+
    |               |cap        |               |cap
    +---------------+           +---------------+
    Returned buffer.            This buffer.
        When the buffers are in this state, both of the split parts retain an atomic reference count on the underlying memory. This means that shared underlying memory will not be deallocated or returned to a pool, until all the split parts have been closed.

        Composite buffers have it a little easier, in that at most only one of the constituent buffers will actually be split. If the split point lands perfectly between two constituent buffers, then a composite buffer can simply split its internal array in two.

        Split buffers support all operations that normal buffers do, including Buffer.ensureWritable(int).

        See the Splitting buffers section for details.

        Specified by:
        split in interface Buffer
        Parameters:
        splitOffset - The offset into this buffer where it should be split. After the split, the data at this offset will be at offset zero in this buffer.
        Returns:
        A new buffer with independent and exclusive ownership over the bytes from the beginning to the given offset of this buffer.

      • compact

        CompositeBuffer compact()
        Description copied from interface: Buffer
        Discards the read bytes, and moves the buffer contents to the beginning of the buffer.
        Specified by:
        compact in interface Buffer
        Returns:
        This buffer instance.

      • setByte

        CompositeBuffer setByte​(int woff,
                        byte value)
        Description copied from interface: BufferAccessor
        Set the given byte value at the given write offset. The Buffer.writerOffset() is not modified. The value is written using a two's complement 8-bit encoding, in ByteOrder.BIG_ENDIAN byte order.
        Specified by:
        setByte in interface BufferAccessor
        Parameters:
        woff - The write offset, an absolute offset into this buffer to write to.
        value - The byte value to write.
        Returns:
        This Buffer.

      • setUnsignedByte

        CompositeBuffer setUnsignedByte​(int woff,
                                int value)
        Description copied from interface: BufferAccessor
        Set the given unsigned byte value at the given write offset. The Buffer.writerOffset() is not modified. The value is written using an unsigned two's complement 8-bit encoding, in ByteOrder.BIG_ENDIAN byte order.
        Specified by:
        setUnsignedByte in interface BufferAccessor
        Parameters:
        woff - The write offset, an absolute offset into this buffer to write to.
        value - The int value to write.
        Returns:
        This Buffer.

      • setChar

        CompositeBuffer setChar​(int woff,
                        char value)
        Description copied from interface: BufferAccessor
        Set the given char value at the given write offset. The Buffer.writerOffset() is not modified. The value is written using a 2-byte UTF-16 encoding, in ByteOrder.BIG_ENDIAN byte order.
        Specified by:
        setChar in interface BufferAccessor
        Parameters:
        woff - The write offset, an absolute offset into this buffer to write to.
        value - The char value to write.
        Returns:
        This Buffer.

      • setShort

        CompositeBuffer setShort​(int woff,
                         short value)
        Description copied from interface: BufferAccessor
        Set the given short value at the given write offset. The Buffer.writerOffset() is not modified. The value is written using a two's complement 16-bit encoding, in ByteOrder.BIG_ENDIAN byte order.
        Specified by:
        setShort in interface BufferAccessor
        Parameters:
        woff - The write offset, an absolute offset into this buffer to write to.
        value - The short value to write.
        Returns:
        This Buffer.

      • setUnsignedShort

        CompositeBuffer setUnsignedShort​(int woff,
                                 int value)
        Description copied from interface: BufferAccessor
        Set the given unsigned short value at the given write offset. The Buffer.writerOffset() is not modified. The value is written using an unsigned two's complement 16-bit encoding, in ByteOrder.BIG_ENDIAN byte order.
        Specified by:
        setUnsignedShort in interface BufferAccessor
        Parameters:
        woff - The write offset, an absolute offset into this buffer to write to.
        value - The int value to write.
        Returns:
        This Buffer.

      • setMedium

        CompositeBuffer setMedium​(int woff,
                          int value)
        Description copied from interface: BufferAccessor
        Set the given int value at the given write offset. The Buffer.writerOffset() is not modified. The value is written using a two's complement 24-bit encoding, in ByteOrder.BIG_ENDIAN byte order.
        Specified by:
        setMedium in interface BufferAccessor
        Parameters:
        woff - The write offset, an absolute offset into this buffer to write to.
        value - The int value to write.
        Returns:
        This Buffer.

      • setUnsignedMedium

        CompositeBuffer setUnsignedMedium​(int woff,
                                  int value)
        Description copied from interface: BufferAccessor
        Set the given unsigned int value at the given write offset. The Buffer.writerOffset() is not modified. The value is written using an unsigned two's complement 24-bit encoding, in ByteOrder.BIG_ENDIAN byte order.
        Specified by:
        setUnsignedMedium in interface BufferAccessor
        Parameters:
        woff - The write offset, an absolute offset into this buffer to write to.
        value - The int value to write.
        Returns:
        This Buffer.

      • setInt

        CompositeBuffer setInt​(int woff,
                       int value)
        Description copied from interface: BufferAccessor
        Set the given int value at the given write offset. The Buffer.writerOffset() is not modified. The value is written using a two's complement 32-bit encoding, in ByteOrder.BIG_ENDIAN byte order.
        Specified by:
        setInt in interface BufferAccessor
        Parameters:
        woff - The write offset, an absolute offset into this buffer to write to.
        value - The int value to write.
        Returns:
        This Buffer.

      • setUnsignedInt

        CompositeBuffer setUnsignedInt​(int woff,
                               long value)
        Description copied from interface: BufferAccessor
        Set the given unsigned int value at the given write offset. The Buffer.writerOffset() is not modified. The value is written using an unsigned two's complement 32-bit encoding, in ByteOrder.BIG_ENDIAN byte order.
        Specified by:
        setUnsignedInt in interface BufferAccessor
        Parameters:
        woff - The write offset, an absolute offset into this buffer to write to.
        value - The long value to write.
        Returns:
        This Buffer.

      • setFloat

        CompositeBuffer setFloat​(int woff,
                         float value)
        Description copied from interface: BufferAccessor
        Set the given float value at the given write offset. The Buffer.writerOffset() is not modified. The value is written using a 32-bit IEEE floating point encoding, in ByteOrder.BIG_ENDIAN byte order.
        Specified by:
        setFloat in interface BufferAccessor
        Parameters:
        woff - The write offset, an absolute offset into this buffer to write to.
        value - The float value to write.
        Returns:
        This Buffer.

      • setLong

        CompositeBuffer setLong​(int woff,
                        long value)
        Description copied from interface: BufferAccessor
        Set the given long value at the given write offset. The Buffer.writerOffset() is not modified. The value is written using a two's complement 64-bit encoding, in ByteOrder.BIG_ENDIAN byte order.
        Specified by:
        setLong in interface BufferAccessor
        Parameters:
        woff - The write offset, an absolute offset into this buffer to write to.
        value - The long value to write.
        Returns:
        This Buffer.

      • setDouble

        CompositeBuffer setDouble​(int woff,
                          double value)
        Description copied from interface: BufferAccessor
        Set the given double value at the given write offset. The Buffer.writerOffset() is not modified. The value is written using a 64-bit IEEE floating point encoding, in ByteOrder.BIG_ENDIAN byte order.
        Specified by:
        setDouble in interface BufferAccessor
        Parameters:
        woff - The write offset, an absolute offset into this buffer to write to.
        value - The double value to write.
        Returns:
        This Buffer.

      • implicitCapacityLimit

        CompositeBuffer implicitCapacityLimit​(int limit)
        Description copied from interface: Buffer
        Set an upper limit to the implicit capacity growth. Buffer write* methods may implicitly grow the buffer capacity instead of throwing a bounds check exception. The implicit capacity limit restricts this growth so the buffer capacity does not automatically grow beyond the given limit. When the limit is reached, and there is no more writable space left, then the write* methods will start throwing exceptions.

        The default limit is the maximum buffer size.

        The limit is carried through Resource.send() calls, but the buffer instances returned from the various split and copy methods will have the default limit set.

        The limit is not impacted by calls to split methods on this buffer. In other words, even though split methods reduce the capacity of this buffer, the set limit, if any, remains the same.

        Specified by:
        implicitCapacityLimit in interface Buffer
        Parameters:
        limit - The maximum size this buffers capacity will implicitly grow to via write* methods.
        Returns:
        This buffer instance.