Package org.apache.datasketches.memory

# Class DefaultMemoryRequestServer

java.lang.Object
org.apache.datasketches.memory.DefaultMemoryRequestServer

All Implemented Interfaces:
  `MemoryRequestServer`

public final class DefaultMemoryRequestServer extends Object implements MemoryRequestServer
This example MemoryRequestServer is simple but demonstrates one of many ways to manage continuous requests for larger or smaller memory. This capability is only available for writable, non-file-memory-mapping resources.

The operation of this implementation is controlled by three conditions:

- origOffHeap: If true, the originally allocated WritableMemory is off-heap.
- oneArena: If true, all subsequent off-heap allocations will use the same Arena obtained from the original off-heap WritableMemory. Otherwise, subsequent off-heap allocations will use a new confined Arena created by this implementation.
- offHeap: If true, all subsequent allocations will be off-heap. If the originally allocated WritableMemory is on-heap, this variable is ignored.

These three variables work together as follows:

- If the original WritableMemory is on-heap, all subsequent allocations will also be on-heap.
- If origOffHeap = true, oneArena = true, and offHeap = true, all subsequent allocations will also be off-heap and associated with the original Arena. It is the responsibility of the user to close the original Arena using a Try-With-Resource block, or directly.
- If the original WritableMemory is off-heap, oneArena is true, and offHeap is false, all subsequent allocations will be on-heap. It is the responsibility of the user to close the original Arena using a Try-With-Resource block, or directly.
- If the original WritableMemory is off-heap, oneArena is false, and offHeap is true, all subsequent allocations will also be off-heap and associated with a new confined Arena assigned by this implementation. It is the responsibility of the user to close the original Arena using a Try-With-Resource block, or directly, and close the last returned new WritableMemory directly.

In summary:

Configuration Options
Original Off-Heap | OneArena | OffHeap | Subsequent Allocations
--- | --- | --- | ---
false | N/A | N/A | All on-heap
true | N/A | false | All on-heap
true | true | true | All off-heap in original Arena
true | false | true | All off-heap in separate Arenas

Author:
  Lee Rhodes

## Constructor Summary

Constructors
Constructor
Description
`DefaultMemoryRequestServer()`
Default constructor.
`DefaultMemoryRequestServer(boolean oneArena, boolean offHeap)`
Optional constructor 1.
`DefaultMemoryRequestServer(long alignmentBytes, ByteOrder byteOrder, boolean oneArena, boolean offHeap)`
Optional constructor 2.

## Method Summary

Modifier and Type
Method
Description
`WritableMemory`
`request(WritableMemory oldWmem, long newCapacityBytes)`
Request a new WritableMemory with the given newCapacityBytes.
`void`
`requestClose(WritableMemory wmemToClose)`
Request to close the given WritableMemory.

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### DefaultMemoryRequestServer

public DefaultMemoryRequestServer()
Default constructor.

### DefaultMemoryRequestServer

public DefaultMemoryRequestServer(boolean oneArena, boolean offHeap)
Optional constructor 1.

Parameters:
  `oneArena` - if true, the original arena will be used for all requested allocations.
  `offHeap` - if true, new allocations will be off-heap.

### DefaultMemoryRequestServer

public DefaultMemoryRequestServer(long alignmentBytes, ByteOrder byteOrder, boolean oneArena, boolean offHeap)
Optional constructor 2.

Parameters:
  `alignmentBytes` - requested segment alignment for all allocations. Typically 1, 2, 4 or 8.
  `byteOrder` - the given ByteOrder. It must be non-null.
  `oneArena` - if true, the same arena will be used for all requested allocations.
  `offHeap` - if true, new allocations will be off-heap.

## Method Details

### request

public WritableMemory request(WritableMemory oldWmem, long newCapacityBytes)
Description copied from interface: `MemoryRequestServer`
Request a new WritableMemory with the given newCapacityBytes.

Specified by:
  `request` in interface `MemoryRequestServer`
Parameters:
  `oldWmem` - the previous WritableMemory to be possibly closed and which provides an associated Arena that may be used for allocating the new WritableMemory. If the arena is null, the requested WritableMemory will be on-heap.
  `newCapacityBytes` - The capacity being requested.
Returns:
  new WritableMemory with the requested capacity.

### requestClose

public void requestClose(WritableMemory wmemToClose)
Description copied from interface: `MemoryRequestServer`
Request to close the given WritableMemory. If applicable, it will be closed by its associated Arena. Be careful. Closing the associated Arena may be closing other resources as well.

Specified by:
  `requestClose` in interface `MemoryRequestServer`
Parameters:
  `wmemToClose` - the given WritableMemory to close.