Method Detail

• onHeapUnpooled

  static BufferAllocator onHeapUnpooled()

  Produces a BufferAllocator that allocates unpooled, on-heap buffers. On-heap buffers have a byte[] internally, and their readable and writable native addresses are zero.

  The concrete Buffer implementation is chosen by MemoryManager.instance().

  Note: This method always creates a new allocator instance. To get a shared and cached allocator instance, use the DefaultBufferAllocators.onHeapAllocator() method instead.

  Returns:

  A non-pooling allocator of on-heap buffers

• offHeapUnpooled

  static BufferAllocator offHeapUnpooled()

  Produces a BufferAllocator that allocates unpooled, off-heap buffers. Off-heap buffers a native memory pointer internally, which can be obtained from their readable and writable native address methods.

  The concrete Buffer implementation is chosen by MemoryManager.instance().

  Note: This method always creates a new allocator instance. To get a shared and cached allocator instance, use the DefaultBufferAllocators.offHeapAllocator() method instead.

  Returns:

  A non-pooling allocator of on-heap buffers

• onHeapPooled

  static BufferAllocator onHeapPooled()

  Produces a pooling BufferAllocator that allocates and recycles on-heap buffers. On-heap buffers have a byte[] internally, and their readable and writable native addresses are zero.

  The concrete Buffer implementation is chosen by MemoryManager.instance().

  Note: This method always creates a new allocator instance. To get a shared and cached allocator instance, use the DefaultBufferAllocators.onHeapAllocator() method instead.

  Returns:

  A pooling allocator of on-heap buffers

• offHeapPooled

  static BufferAllocator offHeapPooled()

  Produces a pooling BufferAllocator that allocates and recycles off-heap buffers. Off-heap buffers a native memory pointer internally, which can be obtained from their readable and writable native address methods.

  The concrete Buffer implementation is chosen by MemoryManager.instance().

  Note: This method always creates a new allocator instance. To get a shared and cached allocator instance, use the DefaultBufferAllocators.offHeapAllocator() method instead.

  Returns:

  A pooling allocator of on-heap buffers

• isPooling

  boolean isPooling()

  Determine if this allocator is pooling and reusing its allocated memory.

  Returns:

  true if this allocator is pooling and reusing its memory, false otherwise.

• getAllocationType

  AllocationType getAllocationType()

  Get the AllocationType from this allocator. This would typically be one of the StandardAllocationTypes.

  Returns:

  The type of allocations performed by this allocator.

• allocate

  Buffer allocate​(int size)

  Allocate a Buffer of the given size in bytes. This method may throw an OutOfMemoryError if there is not enough free memory available to allocate a Buffer of the requested size.

  The buffer will use big endian byte order.

  Parameters:

  size - The size of Buffer to allocate.

  Returns:

  The newly allocated Buffer.

  Throws:

  IllegalStateException - if this allocator has been closed.

• compose

  default CompositeBuffer compose​(Send<Buffer> send)

  Compose the send of a buffer and present them as a single buffer.

  When a composite buffer is closed, all of its constituent component buffers are closed as well.

  See the class documentation for more information on how buffers compose, and what is required of the given buffers for composition to be allowed.

  Parameters:

  send - The sent buffer to compose into a single buffer view.

  Returns:

  A buffer composed of, and backed by, the given buffers.

  Throws:

  IllegalStateException - if one of the sends have already been received. The remaining buffers and sends will be closed and discarded, respectively.

• compose

  default CompositeBuffer compose​(Iterable<Send<Buffer>> sends)

  Compose the given sequence of sends of buffers and present them as a single buffer.

  When a composite buffer is closed, all of its constituent component buffers are closed as well.

  See the class documentation for more information on how buffers compose, and what is required of the given buffers for composition to be allowed.

  Parameters:

  sends - The sent buffers to compose into a single buffer view.

  Returns:

  A buffer composed of, and backed by, the given buffers.

  Throws:

  IllegalStateException - if one of the sends have already been received. The remaining buffers and sends will be closed and discarded, respectively.

• compose

  default CompositeBuffer compose()

  Create an empty composite buffer, that has no components. The buffer can be extended with components using either CompositeBuffer.ensureWritable(int) or CompositeBuffer.extendWith(Send).

  Returns:

  A composite buffer that has no components, and has a capacity of zero.

• constBufferSupplier

  Supplier<Buffer> constBufferSupplier​(byte[] bytes)

  Create a supplier of "constant" Buffers from this allocator, that all have the given byte contents. The buffer has the same capacity as the byte array length, and its write offset is placed at the end, and its read offset is at the beginning, such that the entire buffer contents are readable.

  The buffers produced by the supplier will each have their own independent life-cycle, and closing them will make them inaccessible, just like normally allocated buffers.

  The buffers produced are "constants", in the sense that they are read-only.

  It can generally be expected, but is not guaranteed, that the returned supplier is more resource efficient than allocating and copying memory with other available APIs. In such optimised implementations, the underlying memory baking the buffers will be shared among all the buffers produced by the supplier.

  The primary use case for this API, is when you need to repeatedly produce buffers with the same contents, and you perhaps wish to keep a static final field with these contents. The supplier-based API enforces that each usage get their own distinct buffer instance. Each of these instances cannot interfere with each other, so bugs like closing, or modifying the contents, of a shared buffer cannot occur.

  Parameters:

  bytes - The byte contents of the buffers produced by the returned supplier.

  Returns:

  A supplier of read-only buffers with the given contents.

  Throws:

  IllegalStateException - if this allocator has been closed, but any supplier obtained prior to closing the allocator will continue to work.

• copyOf

  default Buffer copyOf​(byte[] bytes)

  Allocate a Buffer with the same size and contents of the given byte array. The allocated buffer is NOT backed by the given byte array, and changes to the contents of either will not be reflected in the other. This may throw an OutOfMemoryError if there is not enough free memory available to allocate a Buffer of the requested size.

  The allocated buffer will use big endian byte order.

  Parameters:

  bytes - The byte array that determines the size and contents of the new buffer.

  Returns:

  The newly allocated Buffer.

  Throws:

  IllegalStateException - if this allocator has been closed.

• copyOf

  default Buffer copyOf​(String str,
                        Charset charset)

  Allocate a Buffer with the same size and contents of the given String, when interpreted as a sequence of bytes with the given Charset. This may throw an OutOfMemoryError if there is not enough free memory available to allocate a Buffer of the requested size.

  The allocated buffer will use big endian byte order.

  Parameters:

  str - The String that determines the size and contents of the new buffer.

  charset - The Charset that determines how to turn the string into a sequence of bytes.

  Returns:

  The newly allocated Buffer.

  Throws:

  IllegalStateException - if this allocator has been closed.

• copyOf

  default Buffer copyOf​(ByteBuffer buffer)

  Allocate a Buffer with the same size and contents, as the contents of the given ByteBuffer. The allocated buffer is NOT backed by the give byte buffer, and changes to the contents of either will not be reflected in the other. The position and limit of the given byte buffer defines the region of contents that will be copied. The position and limit are not modified by this method. This may throw an OutOfMemoryError if there is not enough free memory available to allocate a Buffer of the requested size.

  The allocated buffer will use big endian byte order, regardless of the byte order of the given buffer. The contents of the byte buffer will be copied without regard to the byte order, as if the bytes are copied one at a time.

  Parameters:

  buffer - The byte buffer, whose contents determine the capacity and contents of the allocated buffer.

  Returns:

  The newly allocated Buffer.

  Throws:

  IllegalStateException - if this allocator has been closed.

• close

  void close()

  Close this allocator, freeing all of its internal resources.

  Existing (currently in-use) allocated buffers will not be impacted by calling this method. If this is a pooling or caching allocator, then existing buffers will be immediately freed when they are closed, instead of being pooled or cached.

  The allocator can no longer be used to allocate more buffers after calling this method. Attempting to allocate from a closed allocator will cause IllegalStateExceptions to be thrown.

  Specified by:

  close in interface AutoCloseable

  Specified by:

  close in interface SafeCloseable