com.bigdata.io

Interface IBufferAccess

public interface IBufferAccess

Interface for access to, and release of, a direct ByteBuffer managed by the DirectBufferPool. A "direct" buffer is a region from the C heap of the native JVM process. Such buffers can be efficient for NIO. They are also efficient when the application needs to store large amounts of data without putting pressure on the Garbage Collector.

CAUTION: Applications MUST use specific patterns when they work with the DirectBufferPool Applications which acquire an IBufferAccess object MUST hold a hard reference to that IBufferAccess while they are using the associated memory block. Failure to follow this pattern WILL result in the backing ByteBuffer being returned to the DirectBufferPool while the application is still using the ByteBuffer (GC will drive this). This situation will lead to corruption for data stored within the ByteBuffer if the buffer recycled and handed off once again via DirectBufferPool.acquire().

Version:

$Id$

Author:

Bryan Thompson

Method Summary

Methods

Modifier and Type	Method and Description
ByteBuffer	buffer() Return the direct ByteBuffer.
void	release() Release the ByteBuffer, returning to owning pool.
void	release(long timeout, TimeUnit unit) Release the ByteBuffer, returning to owning pool.

Method Detail

buffer

ByteBuffer buffer()

Return the direct ByteBuffer.

Caution: DO NOT hold onto a reference to the returned ByteBuffer without also retaining the IBufferAccess object. This can cause the backing ByteBuffer to be returned to the pool, after which it may be handed off to another thread leading to data corruption through concurrent modification to the backing bytes!

Throws:

IllegalStateException - if the buffer has been released.

release

void release()
             throws InterruptedException

Release the ByteBuffer, returning to owning pool. This method will silently succeed if the buffer has already been released.

Throws:

InterruptedException - if an interrupt is noticed while attempting to return the buffer to the pool.

release

void release(long timeout,
           TimeUnit unit)
             throws InterruptedException

Release the ByteBuffer, returning to owning pool. This method will silently succeed if the buffer has already been released.

Parameters:

timeout - The timeout.

unit - The units for that timeout.

Throws:

InterruptedException - if an interrupt is noticed while attempting to return the buffer to the pool.