edu.mines.jtk.util
Class Direct

java.lang.Object
  edu.mines.jtk.util.Direct

public class Direct
extends java.lang.Object

Utilities for direct (native) buffers. Unlike arrays and non-direct buffers that are backed by arrays, the contents of direct buffers cannot move during garbage-collection. This makes direct buffers useful in systems (e.g., OpenGL) that require native pointers to memory.

Memory allocated for a direct buffer typically lies outside the garbage-collected Java heap. That memory is freed when the direct buffer is garbage collected. Unfortunately, garbage collection normally occurs when insufficient space is available inside the Java heap. If insufficient space outside the Java heap is available, then allocation of a new direct buffer may fail with a OutOfMemoryError. This error may occur because direct buffers that are garbage have not yet been collected, perhaps because plenty of space is available inside the Java heap.

A solution to this problem is to perform garbage collection when this error occurs. Normally, a OutOfMemoryError is fatal. However, methods in this class that allocate direct buffers will catch this error and call System.gc() before attempting to allocate the buffer a second time. If that second attempt fails, then no further attempts are made and the error is thrown again. There is no guarantee that this solution will work, but we have not yet seen it fail in tests that repeatedly allocate direct buffers that quickly become garbage.

Version:

2005.06.02

Author:

Dave Hale, Colorado School of Mines

Constructor Summary

Direct()

Method Summary

static java.nio.ByteBuffer	newByteBuffer(byte[] a) Returns a new direct byte buffer.
static java.nio.ByteBuffer	newByteBuffer(int capacity) Returns a new direct byte buffer.
static java.nio.DoubleBuffer	newDoubleBuffer(double[] a) Returns a new direct double buffer.
static java.nio.DoubleBuffer	newDoubleBuffer(int capacity) Returns a new direct double buffer.
static java.nio.FloatBuffer	newFloatBuffer(float[] a) Returns a new direct float buffer.
static java.nio.FloatBuffer	newFloatBuffer(int capacity) Returns a new direct float buffer.
static java.nio.IntBuffer	newIntBuffer(int capacity) Returns a new direct int buffer.
static java.nio.IntBuffer	newIntBuffer(int[] a) Returns a new direct int buffer.
static java.nio.LongBuffer	newLongBuffer(int capacity) Returns a new direct long buffer.
static java.nio.LongBuffer	newLongBuffer(long[] a) Returns a new direct long buffer.
static java.nio.ShortBuffer	newShortBuffer(int capacity) Returns a new direct short buffer.
static java.nio.ShortBuffer	newShortBuffer(short[] a) Returns a new direct short buffer.

Methods inherited from class java.lang.Object

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

Constructor Detail

Direct

public Direct()

Method Detail

newByteBuffer

public static java.nio.ByteBuffer newByteBuffer(int capacity)

Returns a new direct byte buffer.

Parameters:

capacity - the buffer capacity.

Returns:

the new buffer.

newByteBuffer

public static java.nio.ByteBuffer newByteBuffer(byte[] a)

Returns a new direct byte buffer. Allocates the buffer with capacity equal to the length of the specified array, and copies all array elements to the buffer.

Parameters:

a - the array.

Returns:

the new buffer.

newDoubleBuffer

public static java.nio.DoubleBuffer newDoubleBuffer(int capacity)

Returns a new direct double buffer.

Parameters:

capacity - the buffer capacity.

Returns:

the new buffer.

newDoubleBuffer

public static java.nio.DoubleBuffer newDoubleBuffer(double[] a)

Returns a new direct double buffer. Allocates the buffer with capacity equal to the length of the specified array, and copies all array elements to the buffer.

Parameters:

a - the array.

Returns:

the new buffer.

newFloatBuffer

public static java.nio.FloatBuffer newFloatBuffer(int capacity)

Returns a new direct float buffer.

Parameters:

capacity - the buffer capacity.

Returns:

the new buffer.

newFloatBuffer

public static java.nio.FloatBuffer newFloatBuffer(float[] a)

Returns a new direct float buffer. Allocates the buffer with capacity equal to the length of the specified array, and copies all array elements to the buffer.

Parameters:

a - the array.

Returns:

the new buffer.

newIntBuffer

public static java.nio.IntBuffer newIntBuffer(int capacity)

Returns a new direct int buffer.

Parameters:

capacity - the buffer capacity.

Returns:

the new buffer.

newIntBuffer

public static java.nio.IntBuffer newIntBuffer(int[] a)

Returns a new direct int buffer. Allocates the buffer with capacity equal to the length of the specified array, and copies all array elements to the buffer.

Parameters:

a - the array.

Returns:

the new buffer.

newLongBuffer

public static java.nio.LongBuffer newLongBuffer(int capacity)

Returns a new direct long buffer.

Parameters:

capacity - the buffer capacity.

Returns:

the new buffer.

newLongBuffer

public static java.nio.LongBuffer newLongBuffer(long[] a)

Returns a new direct long buffer. Allocates the buffer with capacity equal to the length of the specified array, and copies all array elements to the buffer.

Parameters:

a - the array.

Returns:

the new buffer.

newShortBuffer

public static java.nio.ShortBuffer newShortBuffer(int capacity)

Returns a new direct short buffer.

Parameters:

capacity - the buffer capacity.

Returns:

the new buffer.

newShortBuffer

public static java.nio.ShortBuffer newShortBuffer(short[] a)

Returns a new direct short buffer. Allocates the buffer with capacity equal to the length of the specified array, and copies all array elements to the buffer.

Parameters:

a - the array.

Returns:

the new buffer.