edu.emory.mathcs.util.allocator
Class PoolingAllocator

java.lang.Object
  extended byedu.emory.mathcs.util.allocator.PoolingAllocator
All Implemented Interfaces:
Allocator

public class PoolingAllocator
extends java.lang.Object
implements Allocator

Implements the Allocator using memory buffer pool. Able to enforce memory usage limits; attempts to avoid OutOfMemoryErrors by postponing the allocate requests when there is insufficient memory available in the system. Parameters of the pool are: (1) reserved capacity -- if the current memory usage of the pool is below this value, the allocate request will be always attempted without blocking; (2) maximum capacity -- if the allocate request would inflate the current memory usage above this value, the call will block until more memory is available; (3) security margin -- if the memory available in the system is below this value, the allocate request will block unless current usage is below reserved capacity.

Note: the purpose of this class is to enable control of memory footprint; pooling is NOT intended mainly as a performance optimization. In typical scenarios, allocating memory directly would be faster than reusing buffers through this class, because of associated costs of synchronization. The only possible exception is when buffers are large (in the order of megabytes), when zeroing-out the newly allocated buffer dominates the allocation costs.

Version:
1.0
Author:
Dawid Kurzyniec

Constructor Summary
PoolingAllocator()
          Constructs pooling allocator with default reserved capacity of 1 MB, unlimited maximum capacity and default security margin of 2 MB.
PoolingAllocator(long reserved, long max)
          Constructs pooling allocator with specified reserved and maximum capacity and default security margin of 2 MB.
PoolingAllocator(long reserved, long max, int minLeft)
          Constructs pooling allocator with specified reserved and maximum capacity and specified security margin.
PoolingAllocator(long reserved, long max, int minLeft, edu.emory.mathcs.util.allocator.BufferPool bufpool)
          Constructs pooling allocator with specified reserved and maximum capacity and specified security margin, as well as given buffer pool.
 
Method Summary
 Allocator.Buffer allocate(int size, boolean clear, long timeout)
          Allocate a buffer with specified size.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PoolingAllocator

public PoolingAllocator()
Constructs pooling allocator with default reserved capacity of 1 MB, unlimited maximum capacity and default security margin of 2 MB.


PoolingAllocator

public PoolingAllocator(long reserved,
                        long max)
Constructs pooling allocator with specified reserved and maximum capacity and default security margin of 2 MB.

Parameters:
reserved - the reserved capacity.
max - the maximum capacity.

PoolingAllocator

public PoolingAllocator(long reserved,
                        long max,
                        int minLeft)
Constructs pooling allocator with specified reserved and maximum capacity and specified security margin.

Parameters:
reserved - the reserved capacity.
max - the maximum capacity.
minLeft - the security margin.

PoolingAllocator

public PoolingAllocator(long reserved,
                        long max,
                        int minLeft,
                        edu.emory.mathcs.util.allocator.BufferPool bufpool)
Constructs pooling allocator with specified reserved and maximum capacity and specified security margin, as well as given buffer pool.

Parameters:
reserved - the reserved capacity.
max - the maximum capacity.
minLeft - the security margin.
bufpool - the buffer pool to use.
Method Detail

allocate

public Allocator.Buffer allocate(int size,
                                 boolean clear,
                                 long timeout)
                          throws java.lang.InterruptedException
Description copied from interface: Allocator
Allocate a buffer with specified size. The operation can block if memory limits are exceeded. The timeout value greater than 0 indicates the timeout, the value of 0 will cause immediate return of null if the buffer was not available, and value less than zero will cause to wait for buffer inidefinitely. The clear parameter indicates that the buffer should be zeroed out. Since buffers may be recycled, the buffer returned may contain random garbage if this value is false. If it is set to true, the [0..size] region of the array within the buffer is filled with zeros. This method may return a buffer containing an array larger than requested.

Specified by:
allocate in interface Allocator
Parameters:
size - the requested buffer size.
timeout - the timeout for this operation.
Throws:
java.lang.InterruptedException - if the operation was interrupted.