org.apache.flink.runtime.memory

Class MemoryManager

java.lang.Object

org.apache.flink.runtime.memory.MemoryManager

public class MemoryManager
extends Object

The memory manager governs the memory that Flink uses for sorting, hashing, caching or off-heap state backends (e.g. RocksDB). Memory is represented either in MemorySegments of equal size or in reserved chunks of certain size. Operators allocate the memory either by requesting a number of memory segments or by reserving chunks. Any allocated memory has to be released to be reused later.

The memory segments are represented as off-heap unsafe memory regions (both via MemorySegment). Releasing a memory segment will make it re-claimable by the garbage collector, but does not necessarily immediately releases the underlying memory.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_PAGE_SIZE The default memory page size.
static int	MIN_PAGE_SIZE The minimal memory page size.

Method Summary

Modifier and Type	Method and Description
void	allocatePages(Object owner, Collection<MemorySegment> target, int numberOfPages) Allocates a set of memory segments from this memory manager.
List<MemorySegment>	allocatePages(Object owner, int numPages) Allocates a set of memory segments from this memory manager.
long	availableMemory() Returns the available amount of memory handled by this memory manager.
long	computeMemorySize(double fraction) Computes the memory size corresponding to the fraction of all memory governed by this MemoryManager.
int	computeNumberOfPages(double fraction) Computes to how many pages the given number of bytes corresponds.
static MemoryManager	create(long memorySize, int pageSize) Creates a memory manager with the given capacity and given page size.
<T extends AutoCloseable> OpaqueMemoryResource<T>	getExternalSharedMemoryResource(String type, LongFunctionWithException<T,Exception> initializer, long numBytes) Acquires a shared resource, identified by a type string.
long	getMemorySize() Returns the total size of memory handled by this memory manager.
int	getPageSize() Gets the size of the pages handled by the memory manager.
<T extends AutoCloseable> OpaqueMemoryResource<T>	getSharedMemoryResourceForManagedMemory(String type, LongFunctionWithException<T,Exception> initializer, double fractionToInitializeWith) Acquires a shared memory resource, identified by a type string.
boolean	isShutdown() Checks whether the MemoryManager has been shut down.
void	release(Collection<MemorySegment> segments) Tries to release many memory segments together.
void	release(MemorySegment segment) Tries to release the memory for the specified segment.
void	releaseAll(Object owner) Releases all memory segments for the given owner.
void	releaseAllMemory(Object owner) Releases all reserved memory chunks from an owner to this memory manager.
void	releaseMemory(Object owner, long size) Releases a memory chunk of a certain size from an owner to this memory manager.
void	reserveMemory(Object owner, long size) Reserves a memory chunk of a certain size for an owner from this memory manager.
void	shutdown() Shuts the memory manager down, trying to release all the memory it managed.
boolean	verifyEmpty() Checks if the memory manager's memory is completely available (nothing allocated at the moment).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_PAGE_SIZE

public static final int DEFAULT_PAGE_SIZE

The default memory page size. Currently set to 32 KiBytes.

See Also:

Constant Field Values

MIN_PAGE_SIZE

public static final int MIN_PAGE_SIZE

The minimal memory page size. Currently set to 4 KiBytes.

See Also:

Constant Field Values

Method Detail

shutdown

public void shutdown()

Shuts the memory manager down, trying to release all the memory it managed. Depending on implementation details, the memory does not necessarily become reclaimable by the garbage collector, because there might still be references to allocated segments in the code that allocated them from the memory manager.

isShutdown

@VisibleForTesting
public boolean isShutdown()

Checks whether the MemoryManager has been shut down.

Returns:

True, if the memory manager is shut down, false otherwise.

verifyEmpty

public boolean verifyEmpty()

Checks if the memory manager's memory is completely available (nothing allocated at the moment).

Returns:

True, if the memory manager is empty and valid, false if it is not empty or corrupted.

allocatePages

public List<MemorySegment> allocatePages(Object owner,
                                         int numPages)
                                  throws MemoryAllocationException

Allocates a set of memory segments from this memory manager.

The total allocated memory will not exceed its size limit, announced in the constructor.

Parameters:

owner - The owner to associate with the memory segment, for the fallback release.

numPages - The number of pages to allocate.

Returns:

A list with the memory segments.

Throws:

MemoryAllocationException - Thrown, if this memory manager does not have the requested amount of memory pages any more.

allocatePages

public void allocatePages(Object owner,
                          Collection<MemorySegment> target,
                          int numberOfPages)
                   throws MemoryAllocationException

Allocates a set of memory segments from this memory manager.

The total allocated memory will not exceed its size limit, announced in the constructor.

Parameters:

owner - The owner to associate with the memory segment, for the fallback release.

target - The list into which to put the allocated memory pages.

numberOfPages - The number of pages to allocate.

Throws:

MemoryAllocationException - Thrown, if this memory manager does not have the requested amount of memory pages any more.

release

public void release(MemorySegment segment)

Tries to release the memory for the specified segment.

If the segment has already been released, it is only freed. If it is null or has no owner, the request is simply ignored. The segment is only freed and made eligible for reclamation by the GC. The segment will be returned to the memory pool, increasing its available limit for the later allocations.

Parameters:

segment - The segment to be released.

release

public void release(Collection<MemorySegment> segments)

Tries to release many memory segments together.

The segment is only freed and made eligible for reclamation by the GC. Each segment will be returned to the memory pool, increasing its available limit for the later allocations.

Parameters:

segments - The segments to be released.

releaseAll

public void releaseAll(Object owner)

Releases all memory segments for the given owner.

Parameters:

owner - The owner memory segments are to be released.

reserveMemory

public void reserveMemory(Object owner,
                          long size)
                   throws MemoryReservationException

Reserves a memory chunk of a certain size for an owner from this memory manager.

Parameters:

owner - The owner to associate with the memory reservation, for the fallback release.

size - size of memory to reserve.

Throws:

MemoryReservationException - Thrown, if this memory manager does not have the requested amount of memory any more.

releaseMemory

public void releaseMemory(Object owner,
                          long size)

Releases a memory chunk of a certain size from an owner to this memory manager.

Parameters:

owner - The owner to associate with the memory reservation, for the fallback release.

size - size of memory to release.

releaseAllMemory

public void releaseAllMemory(Object owner)

Releases all reserved memory chunks from an owner to this memory manager.

Parameters:

owner - The owner to associate with the memory reservation, for the fallback release.

getSharedMemoryResourceForManagedMemory

public <T extends AutoCloseable> OpaqueMemoryResource<T> getSharedMemoryResourceForManagedMemory(String type,
                                                                                                 LongFunctionWithException<T,Exception> initializer,
                                                                                                 double fractionToInitializeWith)
                                                                                          throws Exception

Acquires a shared memory resource, identified by a type string. If the resource already exists, this returns a descriptor to the resource. If the resource does not yet exist, the given memory fraction is reserved and the resource is initialized with that size.

The memory for the resource is reserved from the memory budget of this memory manager (thus determining the size of the resource), but resource itself is opaque, meaning the memory manager does not understand its structure.

The OpaqueMemoryResource object returned from this method must be closed once not used any further. Once all acquisitions have closed the object, the resource itself is closed.

Important: The failure semantics are as follows: If the memory manager fails to reserve the memory, the external resource initializer will not be called. If an exception is thrown when the opaque resource is closed (last lease is released), the memory manager will still un-reserve the memory to make sure its own accounting is clean. The exception will need to be handled by the caller of OpaqueMemoryResource.close(). For example, if this indicates that native memory was not released and the process might thus have a memory leak, the caller can decide to kill the process as a result.

Throws:

Exception

getExternalSharedMemoryResource

public <T extends AutoCloseable> OpaqueMemoryResource<T> getExternalSharedMemoryResource(String type,
                                                                                         LongFunctionWithException<T,Exception> initializer,
                                                                                         long numBytes)
                                                                                  throws Exception

Acquires a shared resource, identified by a type string. If the resource already exists, this returns a descriptor to the resource. If the resource does not yet exist, the method initializes a new resource using the initializer function and given size.

The resource opaque, meaning the memory manager does not understand its structure.

The OpaqueMemoryResource object returned from this method must be closed once not used any further. Once all acquisitions have closed the object, the resource itself is closed.

Throws:

Exception

getPageSize

public int getPageSize()

Gets the size of the pages handled by the memory manager.

Returns:

The size of the pages handled by the memory manager.

getMemorySize

public long getMemorySize()

Returns the total size of memory handled by this memory manager.

Returns:

The total size of memory.

availableMemory

public long availableMemory()

Returns the available amount of memory handled by this memory manager.

Returns:

The available amount of memory.

computeNumberOfPages

public int computeNumberOfPages(double fraction)

Computes to how many pages the given number of bytes corresponds. If the given number of bytes is not an exact multiple of a page size, the result is rounded down, such that a portion of the memory (smaller than the page size) is not included.

Parameters:

fraction - the fraction of the total memory per slot

Returns:

The number of pages to which

computeMemorySize

public long computeMemorySize(double fraction)

Computes the memory size corresponding to the fraction of all memory governed by this MemoryManager.

Parameters:

fraction - The fraction of all memory governed by this MemoryManager

Returns:

The memory size corresponding to the memory fraction

create

public static MemoryManager create(long memorySize,
                                   int pageSize)

Creates a memory manager with the given capacity and given page size.

This is a production version of MemoryManager which checks for memory leaks (verifyEmpty()) once the owner of the MemoryManager is ready to dispose.

Parameters:

memorySize - The total size of the off-heap memory to be managed by this memory manager.

pageSize - The size of the pages handed out by the memory manager.