Interface MemoryManager

  • All Known Implementing Classes:
    ByteBufferMemoryManager, UnsafeMemoryManager

    public interface MemoryManager
    The choice of MemoryManager implementation also determines the choice of Buffer implementation. It is the MemoryManager that implement memory allocation, and how to wrap the allocated memory in a Buffer interface.
    • Method Detail

      • instance

        static MemoryManager instance()
        Get the default, or currently configured, memory managers instance.
        A MemoryManagers instance.
      • onLeakDetected

        static SafeCloseable onLeakDetected​(Consumer<LeakInfo> callback)
        Register a callback that will be called whenever a Buffer instance is leaked.

        Be mindful that the callback must be fast, and not take any locks or call any blocking methods, as this might interfere with the garbage collectors reference processing and cleaning.

        This also applies to callbacks that perform logging. In these cases, asynchronous logging should be preferred, for the avoidance of blocking calls and IO.

        If the same callback object is registered multiple times, it will only be informed once for each leak, but each of the associated SafeCloseable objects will need to be closed before the callback is removed.

        callback - The callback that will be called when a buffer leak is detected.
        An SafeCloseable instance that, when closed, removes the given callback again.
      • using

        static <T> T using​(MemoryManager manager,
                           Supplier<T> supplier)
        Temporarily override the default configured memory managers instance.

        Calls to instance() from within the given supplier will get the given managers instance.

        Type Parameters:
        T - The result type from the supplier.
        manager - Override the default configured managers instance with this instance.
        supplier - The supplier function to be called while the override is in place.
        The result from the supplier.
      • unsafeWrap

        static Buffer unsafeWrap​(byte[] array)
        Create a new on-heap Buffer instance that directly wraps the given array.

        This is unsafe because it allows the memory (the array) to be aliased (multiple references to the same memory) in an uncontrolled way.

        The returned buffer will be read-only, but changes to the byte array will be reflected in the buffers contents.

        Note: Wrapping buffers created with this method are not subject to leak detection, and if they are garbage collected without being closed first, then no callback will be issued to any on-leak callback handler.

        array - The byte array that will be embedded in the created buffer.
        A buffer that wraps the given byte array
      • allocateShared

        Buffer allocateShared​(AllocatorControl allocatorControl,
                              long size,
                              Function<Drop<Buffer>,​Drop<Buffer>> dropDecorator,
                              AllocationType allocationType)
        Allocates a shared buffer. "Shared" is the normal type of buffer, and means the buffer permit concurrent access from multiple threads, within the limited thread-safety guarantees of the Buffer interface.
        allocatorControl - Call-back interface for controlling the allocator that requested the allocation of this buffer.
        size - The size of the buffer to allocate. This size is assumed to be valid for the implementation.
        dropDecorator - A function to decorate the memory managers Drop instance. The Drop instance returned by this function will be used when the buffer is closed.
        allocationType - The type of allocation to perform. Typically, one of the StandardAllocationTypes.
        A Buffer instance with the given configuration.
        IllegalArgumentException - For unknown AllocationTypes.
      • allocateConstChild

        Buffer allocateConstChild​(Buffer readOnlyConstParent)
        Allocates a constant buffer based on the given parent. A "constant" buffer is conceptually similar to a read-only buffer, but the implementation may share the underlying memory across multiple buffer instance - something that is normally not allowed by the API. This allows efficient implementation of the BufferAllocator.constBufferSupplier(byte[]) method.

        Note: The const-parent buffer must be allocated by this memory manager.

        readOnlyConstParent - The read-only parent buffer for which a const buffer should be created. The parent buffer is allocated in the usual way, with allocateShared(AllocatorControl, long, Function, AllocationType), initialised with contents, and then made read-only.
        A const buffer with the same size, contents, and read-only state of the given parent buffer.
      • unwrapRecoverableMemory

        Object unwrapRecoverableMemory​(Buffer buf)
        Create an object that represents the internal memory of the given buffer.
        buf - The buffer to unwrap.
        The internal memory of the given buffer, as an opaque object.
      • recoverMemory

        Buffer recoverMemory​(AllocatorControl allocatorControl,
                             Object recoverableMemory,
                             Drop<Buffer> drop)
        Recover the memory from a prior unwrapRecoverableMemory(Buffer) call, and wrap it in a Buffer instance.
        allocatorControl - The allocator control to attach to the buffer.
        recoverableMemory - The opaque memory to use for the buffer.
        drop - The Drop instance to use when the buffer is closed.
        A Buffer instance backed by the given recovered memory.
      • sliceMemory

        Object sliceMemory​(Object memory,
                           int offset,
                           int length)
        Produces a slice of the given internal memory representation object.
        memory - The opaque memory to slice.
        offset - The offset into the memory to slice from.
        length - The length of the slice.
        A new opaque memory instance that represents the given slice of the original.
      • clearMemory

        void clearMemory​(Object memory)
        Overwrite the given recoverable memory object with zeroes, erasing all data that it contains.

        This is used by the SensitiveBufferAllocator to erase data on deallocation.

        memory - The memory that should be overwritten.
      • implementationName

        String implementationName()
        Get the name for this implementation, which can be used for finding this particular implementation via the lookupImplementation(String) method.
        The name of this memory managers implementation.