-
- All Known Implementing Classes:
ByteBufferMemoryManager
,UnsafeMemoryManager
@UnstableApi public interface MemoryManager
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Modifier and Type Method Description Buffer
allocateConstChild(Buffer readOnlyConstParent)
Allocates a constant buffer based on the given parent.Buffer
allocateShared(AllocatorControl allocatorControl, long size, Function<Drop<Buffer>,Drop<Buffer>> dropDecorator, AllocationType allocationType)
Allocates a shared buffer.static Stream<ServiceLoader.Provider<MemoryManager>>
availableManagers()
Get a stream of all available memory managers.void
clearMemory(Object memory)
Overwrite the given recoverable memory object with zeroes, erasing all data that it contains.String
implementationName()
Get the name for this implementation, which can be used for finding this particular implementation via thelookupImplementation(String)
method.static MemoryManager
instance()
Get the default, or currently configured, memory managers instance.static Optional<MemoryManager>
lookupImplementation(String implementationName)
Find aMemoryManager
implementation by its implementation name.static SafeCloseable
onLeakDetected(Consumer<LeakInfo> callback)
Register a callback that will be called whenever aBuffer
instance is leaked.Buffer
recoverMemory(AllocatorControl allocatorControl, Object recoverableMemory, Drop<Buffer> drop)
Recover the memory from a priorunwrapRecoverableMemory(Buffer)
call, and wrap it in aBuffer
instance.Object
sliceMemory(Object memory, int offset, int length)
Produces a slice of the given internal memory representation object.static Buffer
unsafeWrap(byte[] array)
Create a new on-heapBuffer
instance that directly wraps the given array.Object
unwrapRecoverableMemory(Buffer buf)
Create an object that represents the internal memory of the given buffer.static <T> T
using(MemoryManager manager, Supplier<T> supplier)
Temporarily override the default configured memory managers instance.
-
-
-
Method Detail
-
instance
static MemoryManager instance()
Get the default, or currently configured, memory managers instance.- Returns:
- A MemoryManagers instance.
-
onLeakDetected
@UnstableApi static SafeCloseable onLeakDetected(Consumer<LeakInfo> callback)
Register a callback that will be called whenever aBuffer
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.- Parameters:
callback
- The callback that will be called when a buffer leak is detected.- Returns:
- 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.- Parameters:
manager
- Override the default configured managers instance with this instance.supplier
- The supplier function to be called while the override is in place.- Returns:
- The result from the supplier.
-
availableManagers
static Stream<ServiceLoader.Provider<MemoryManager>> availableManagers()
Get a stream of all available memory managers.- Returns:
- A stream of providers of memory managers instances.
-
lookupImplementation
static Optional<MemoryManager> lookupImplementation(String implementationName)
Find aMemoryManager
implementation by its implementation name.- Parameters:
implementationName
- The named implementation to look for.- Returns:
- A
MemoryManager
implementation, if any was found.
-
unsafeWrap
@UnstableApi static Buffer unsafeWrap(byte[] array)
Create a new on-heapBuffer
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.
- Parameters:
array
- The byte array that will be embedded in the created buffer.- Returns:
- 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 theBuffer
interface.- Parameters:
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 managersDrop
instance. TheDrop
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.- Returns:
- A
Buffer
instance with the given configuration. - Throws:
IllegalArgumentException
- For unknownAllocationType
s.
-
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 theBufferAllocator.constBufferSupplier(byte[])
method.Note: The const-parent buffer must be allocated by this memory manager.
- Parameters:
readOnlyConstParent
- The read-only parent buffer for which a const buffer should be created. The parent buffer is allocated in the usual way, withallocateShared(AllocatorControl, long, Function, AllocationType)
, initialised with contents, and then made read-only.- Returns:
- 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.- Parameters:
buf
- The buffer to unwrap.- Returns:
- 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 priorunwrapRecoverableMemory(Buffer)
call, and wrap it in aBuffer
instance.
-
sliceMemory
Object sliceMemory(Object memory, int offset, int length)
Produces a slice of the given internal memory representation object.- Parameters:
memory
- The opaque memory to slice.offset
- The offset into the memory to slice from.length
- The length of the slice.- Returns:
- 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.- Parameters:
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 thelookupImplementation(String)
method.- Returns:
- The name of this memory managers implementation.
-
-