Sea 0.3.0

gov.lbl.dsd.sea.nio.util
Class BufferPool

java.lang.Object
  extended bygov.lbl.dsd.sea.nio.util.BufferPool

public class BufferPool
extends Object

Efficient thread-safe pool of ByteBuffers for high performance NIO applications. Using a buffer pool can drastically reduce memory allocation, memory copying and garbage collection by taking buffers from the pool when needed, and recycling them back to the pool when they are no more needed.

There is a trade-off here: The improved performance a pool promises comes at the expense of larger overall memory footprint, since buffers in the pool are not subject to intermediate garbage collection (unless the entire pool is no more referenced or cleared, of course).

Once you have taken a buffer via the take method from the pool, you can modify it in any way desired. Once you have recycled a buffer via the put method back to the pool you MUST NOT modify it anymore, NOT EVEN it's mark, position or limit, whether directly or indirectly!

On put the pool will ignore buffers with buffer.capacity() < bufferCapacity or when the aggregate capacity of all buffers in the pool would become larger than maxPoolCapacity.

On take the pool will return a cleared buffer with at least the given bufferCapacity, which will be a direct or heap buffer, depending on the preferDirect flag. In any case, the returned buffer will have the given byteOrder, or BIG_ENDIAN byte order if byteOrder is null.

If empty on take the pool will create a new buffer and return that. (The buffer pool is smart in avoiding allocating too many direct buffers and in its preference strategies).

Hint: At least in jdk-1.4.2 the total maximum amount of direct buffers that may be allocated is 64MB by default. You can change this via java -XX:MaxDirectMemorySize=256m. See bug 4879883 on Java Bug Parade. See http://iais.kemsu.ru/odocs/javax/JSDK.Src/java/nio/Bits.java

Version:
$Revision: 1.5 $, $Date: 2004/07/16 23:44:51 $

Constructor Summary
BufferPool(long maxPoolCapacity, int bufferCapacity, boolean preferDirect, ByteOrder byteOrder)
          Creates a new pool with the given properties.
 
Method Summary
 void clear()
          Removes all buffers from the pool.
 void put(ByteBuffer buffer)
          Recycles a buffer back into the pool (adds it to the pool).
 ByteBuffer take()
          Returns a cleared buffer from the pool, or creates and returns a new buffer.
 String toString()
          Returns a summary statistics representation of the receiver.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

BufferPool

public BufferPool(long maxPoolCapacity,
                  int bufferCapacity,
                  boolean preferDirect,
                  ByteOrder byteOrder)
Creates a new pool with the given properties.

Method Detail

put

public void put(ByteBuffer buffer)
Recycles a buffer back into the pool (adds it to the pool).

Parameters:
buffer - the buffer to put into the pool.

take

public ByteBuffer take()
Returns a cleared buffer from the pool, or creates and returns a new buffer.

Returns:
a buffer from the pool.

clear

public void clear()
Removes all buffers from the pool.


toString

public String toString()
Returns a summary statistics representation of the receiver.


Sea 0.3.0