io.humble.ferry

Class Buffer

java.lang.Object

io.humble.ferry.RefCounted

io.humble.ferry.Buffer

public class Buffer
extends RefCounted

Allows Java code to get data from a native buffers, and optionally modify native memory directly.

When accessing from Java, you can copy in and
out ranges of buffers. You can do this by-copy
(which is safer but a little slower) or by-reference
where you directly access underlying C++/native
memory from Java. Take special care if you decide
that native access is required.

When accessing from C++, you get direct access to
the underlying buffer.

To make an Buffer object that is not a Humble internal object,
pass in null for the RefCounted parameter.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Buffer.Type Types of data that are in this buffer.

Constructor Summary

Constructors

Constructor and Description
Buffer(long ignore1, boolean ignore2) DO NOT USE THIS CONSTRUCTOR - USE make(RefCounted,int) INSTEAD.

Method Summary

Modifier and Type	Method and Description
Buffer	copyReference() Create a new Buffer object that is actually referring to the exact same underlying Native object.
void	delete() Releases ths instance of Buffer and frees any underlying native memory.
boolean	equals(Object obj) Compares two values, returning true if the underlying objects in native code are the same object.
void	get(int srcPos, byte[] dest, int destPos, int length) Absolute bulk get method.
void	get(int srcPos, char[] dest, int destPos, int length) Absolute bulk get method.
void	get(int srcPos, double[] dest, int destPos, int length) Absolute bulk get method.
void	get(int srcPos, float[] dest, int destPos, int length) Absolute bulk get method.
void	get(int srcPos, int[] dest, int destPos, int length) Absolute bulk get method.
void	get(int srcPos, long[] dest, int destPos, int length) Absolute bulk get method.
void	get(int srcPos, short[] dest, int destPos, int length) Absolute bulk get method.
int	getBufferSize() Get the current maximum number of bytes that can be safely placed in this buffer.
byte[]	getByteArray(int offset, int length) Returns up to length bytes, starting at offset in the underlying buffer we're managing.
ByteBuffer	getByteBuffer(int offset, int length) Returns up to length bytes, starting at offset in the underlying buffer we're managing.
ByteBuffer	getByteBuffer(int offset, int length, AtomicReference<JNIReference> referenceReturn) Returns up to length bytes, starting at offset in the underlying buffer we're managing, and also passed back a JNIReference that can optionally be used by the caller to free the underlying native memory.
int	getSize() Returns the size, in units of #getType() of this buffer.
Buffer.Type	getType() Get the type this buffer was created as.
static int	getTypeSize(Buffer.Type type) Returns the size, in bytes, of elements of given Type.
int	hashCode() Get a hashable value for this object.
static Buffer	make(RefCounted requestor, Buffer.Type type, int numElements, boolean zero) Allocate a new buffer of at least bufferSize.
static Buffer	make(RefCounted requestor, byte[] buffer, int offset, int length) Allocate a new Buffer, and copy the data in buffer into the new Buffer object.
static Buffer	make(RefCounted requestor, ByteBuffer directByteBuffer, int offset, int length) Create a new Buffer object that uses the direct byte buffer passed in by reference (i.e.
static Buffer	make(RefCounted requestor, int bufferSize) Allocate a new buffer of at least bufferSize.
void	put(byte[] src, int srcPos, int destPos, int length) Absolute bulk put method.
void	put(char[] src, int srcPos, int destPos, int length) Absolute bulk put method.
void	put(double[] src, int srcPos, int destPos, int length) Absolute bulk put method.
void	put(float[] src, int srcPos, int destPos, int length) Absolute bulk put method.
void	put(int[] src, int srcPos, int destPos, int length) Absolute bulk put method.
void	put(long[] src, int srcPos, int destPos, int length) Absolute bulk put method.
void	put(short[] src, int srcPos, int destPos, int length) Absolute bulk put method.
void	setType(Buffer.Type type) Reset the buffer type to a new type.
String	toString() Prints the same as Object.toString() but appends the maximum number of bytes that will fit in this Buffer, the type of the Buffer, and the maximum size in units of Buffer.Type that will fit in the Buffer.

Methods inherited from class io.humble.ferry.RefCounted

getCurrentRefCount

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Buffer

public Buffer(long ignore1,
              boolean ignore2)

DO NOT USE THIS CONSTRUCTOR - USE make(RefCounted,int) INSTEAD.

Internal Only. Do not allocate this object using new. Not part of public API.

Unfortunately this constructor is public because the internal implementation needs it to be, but do not pass in values to this method as you may end up crashing the virtual machine.

Parameters:

ignore1 - ignore.

ignore2 - ignore.

Method Detail

delete

public void delete()

Releases ths instance of Buffer and frees any underlying native memory.

Releases any underlying native memory and marks this object as invalid.

Normally Ferry manages when to release native memory.

In the unlikely event you want to control EXACTLY when a native object is released, each Humble object has a RefCounted.delete() method that you can use. Once you call RefCounted.delete(), you must ENSURE your object is never referenced again from that Java object -- Ferry tries to help you avoid crashes if you accidentally use an object after deletion but on this but we cannot offer 100% protection (specifically if another thread is accessing that object EXACTLY when you RefCounted.delete() it).

Overrides:

delete in class RefCounted

copyReference

public Buffer copyReference()

Create a new Buffer object that is actually referring to the exact same underlying Native object.

Overrides:

copyReference in class RefCounted

Returns:

the new Java object.

equals

public boolean equals(Object obj)

Compares two values, returning true if the underlying objects in native code are the same object. That means you can have two different Java objects, but when you do a comparison, you'll find out they are the EXACT same object.

Overrides:

equals in class Object

Returns:

True if the underlying native object is the same. False otherwise.

hashCode

public int hashCode()

Get a hashable value for this object.

Overrides:

hashCode in class Object

Returns:

the hashable value.

put

public void put(byte[] src,
                int srcPos,
                int destPos,
                int length)

Absolute bulk put method.

This method transfers bytes into this buffer from the given source array. If there are more bytes to be copied from the array than there is space remaining at the specified destination offset, then no bytes are transferred and a java.nio.BufferOverflowException is thrown.

This method is equivalent to calling getByteBuffer(int, int) yourself and copying the bytes over, but is more efficient in the JNIMemoryManager.MemoryModel.NATIVE_BUFFERS memory model.

Parameters:

src - The array from which bytes are to be read. Must be non null.

srcPos - The offset within src of the first byte to be read; must be non-negative and less than src.length

destPos - The offset in the Buffer where you want to copy data to. Must be non-negative and less than getBufferSize()

length - The number of bytes to be read from src; must be non-negative and no larger than src.length - srcPos

Throws:

NullPointerException - if src is null.

IndexOutOfBoundsException - if the preconditions on the arguments mentioned above are not honored.

BufferOverflowException - if there is insufficient space in this Buffer.

get

public void get(int srcPos,
                byte[] dest,
                int destPos,
                int length)

Absolute bulk get method.

This method transfers bytes from this Buffer into the given dest array. If there are fewer bytes in the Buffer starting at position srcPos than are required to satisfy the request, then no bytes are transferred and a BufferUnderflowException is thrown.

This method is equivalent to calling getByteBuffer(int, int) yourself and reading the bytes out, but is more efficient in the JNIMemoryManager.MemoryModel.NATIVE_BUFFERS memory model.

Parameters:

srcPos - The offset in the Buffer where you want to start copying data from. Must be non-negative and less than getBufferSize()

dest - The array to which bytes are to be written. Must be non null.

destPos - The offset within dest of the first byte to be written; must be non-negative and less than dest.length

length - The number of bytes to be copied into dest; must be non-negative and no larger than dest.length - destPos

Throws:

NullPointerException - if dest is null.

IndexOutOfBoundsException - if the preconditions on the arguments mentioned above are not honored.

BufferOverflowException - if there is insufficient data in this Buffer to satisfy the request.

put

public void put(short[] src,
                int srcPos,
                int destPos,
                int length)

Absolute bulk put method.

This method transfers shorts into this buffer from the given source array. If there are more shorts to be copied from the array than there is space remaining at the specified destination offset, then no shorts are transferred and a java.nio.BufferOverflowException is thrown.

This method is equivalent to calling getByteBuffer(int, int) yourself and copying the bytes over, but is more efficient in the JNIMemoryManager.MemoryModel.NATIVE_BUFFERS memory model.

Parameters:

src - The array from which shorts are to be read. Must be non null.

srcPos - The offset within src of the first short to be read; must be non-negative and less than src.length

destPos - The offset in the Buffer where you want to copy data to. Must be non-negative and less than getBufferSize()

length - The number of shorts to be read from src; must be non-negative and no larger than src.length - srcPos

Throws:

NullPointerException - if src is null.

IndexOutOfBoundsException - if the preconditions on the arguments mentioned above are not honored.

BufferOverflowException - if there is insufficient space in this Buffer.

get

public void get(int srcPos,
                short[] dest,
                int destPos,
                int length)

Absolute bulk get method.

This method transfers shorts from this Buffer into the given dest array. If there are fewer shorts in the Buffer starting at position srcPos than are required to satisfy the request, then no shorts are transferred and a BufferUnderflowException is thrown.

This method is equivalent to calling getByteBuffer(int, int) yourself and reading the bytes out, but is more efficient in the JNIMemoryManager.MemoryModel.NATIVE_BUFFERS memory model.

Parameters:

srcPos - The offset in the Buffer where you want to start copying data from. Must be non-negative and less than getBufferSize()

dest - The array to which shorts are to be written. Must be non null.

destPos - The offset within dest of the first short to be written; must be non-negative and less than dest.length

length - The number of shorts to be copied into dest; must be non-negative and no larger than dest.length - destPos

Throws:

NullPointerException - if dest is null.

IndexOutOfBoundsException - if the preconditions on the arguments mentioned above are not honored.

BufferOverflowException - if there is insufficient data in this Buffer to satisfy the request.

put

public void put(int[] src,
                int srcPos,
                int destPos,
                int length)

Absolute bulk put method.

This method transfers ints into this buffer from the given source array. If there are more ints to be copied from the array than there is space remaining at the specified destination offset, then no ints are transferred and a java.nio.BufferOverflowException is thrown.

This method is equivalent to calling getByteBuffer(int, int) yourself and copying the bytes over, but is more efficient in the JNIMemoryManager.MemoryModel.NATIVE_BUFFERS memory model.

Parameters:

src - The array from which ints are to be read. Must be non null.

srcPos - The offset within src of the first int to be read; must be non-negative and less than src.length

destPos - The offset in the Buffer where you want to copy data to. Must be non-negative and less than getBufferSize()

length - The number of ints to be read from src; must be non-negative and no larger than src.length - srcPos

Throws:

NullPointerException - if src is null.

IndexOutOfBoundsException - if the preconditions on the arguments mentioned above are not honored.

BufferOverflowException - if there is insufficient space in this Buffer.

get

public void get(int srcPos,
                int[] dest,
                int destPos,
                int length)

Absolute bulk get method.

This method transfers ints from this Buffer into the given dest array. If there are fewer ints in the Buffer starting at position srcPos than are required to satisfy the request, then no ints are transferred and a BufferUnderflowException is thrown.

This method is equivalent to calling getByteBuffer(int, int) yourself and reading the bytes out, but is more efficient in the JNIMemoryManager.MemoryModel.NATIVE_BUFFERS memory model.

Parameters:

srcPos - The offset in the Buffer where you want to start copying data from. Must be non-negative and less than getBufferSize()

dest - The array to which ints are to be written. Must be non null.

destPos - The offset within dest of the first int to be written; must be non-negative and less than dest.length

length - The number of ints to be copied into dest; must be non-negative and no larger than dest.length - destPos

Throws:

NullPointerException - if dest is null.

IndexOutOfBoundsException - if the preconditions on the arguments mentioned above are not honored.

BufferOverflowException - if there is insufficient data in this Buffer to satisfy the request.

put

public void put(long[] src,
                int srcPos,
                int destPos,
                int length)

Absolute bulk put method.

This method transfers longs into this buffer from the given source array. If there are more longs to be copied from the array than there is space remaining at the specified destination offset, then no longs are transferred and a java.nio.BufferOverflowException is thrown.

This method is equivalent to calling getByteBuffer(int, int) yourself and copying the bytes over, but is more efficient in the JNIMemoryManager.MemoryModel.NATIVE_BUFFERS memory model.

Parameters:

src - The array from which longs are to be read. Must be non null.

srcPos - The offset within src of the first long to be read; must be non-negative and less than src.length

destPos - The offset in the Buffer where you want to copy data to. Must be non-negative and less than getBufferSize()

length - The number of longs to be read from src; must be non-negative and no larger than src.length - srcPos

Throws:

NullPointerException - if src is null.

IndexOutOfBoundsException - if the preconditions on the arguments mentioned above are not honored.

BufferOverflowException - if there is insufficient space in this Buffer.

get

public void get(int srcPos,
                long[] dest,
                int destPos,
                int length)

Absolute bulk get method.

This method transfers longs from this Buffer into the given dest array. If there are fewer longs in the Buffer starting at position srcPos than are required to satisfy the request, then no longs are transferred and a BufferUnderflowException is thrown.

This method is equivalent to calling getByteBuffer(int, int) yourself and reading the bytes out, but is more efficient in the JNIMemoryManager.MemoryModel.NATIVE_BUFFERS memory model.

Parameters:

srcPos - The offset in the Buffer where you want to start copying data from. Must be non-negative and less than getBufferSize()

dest - The array to which longs are to be written. Must be non null.

destPos - The offset within dest of the first long to be written; must be non-negative and less than dest.length

length - The number of longs to be copied into dest; must be non-negative and no larger than dest.length - destPos

Throws:

NullPointerException - if dest is null.

IndexOutOfBoundsException - if the preconditions on the arguments mentioned above are not honored.

BufferOverflowException - if there is insufficient data in this Buffer to satisfy the request.

put

public void put(double[] src,
                int srcPos,
                int destPos,
                int length)

Absolute bulk put method.

This method transfers doubles into this buffer from the given source array. If there are more doubles to be copied from the array than there is space remaining at the specified destination offset, then no doubles are transferred and a java.nio.BufferOverflowException is thrown.

This method is equivalent to calling getByteBuffer(int, int) yourself and copying the bytes over, but is more efficient in the JNIMemoryManager.MemoryModel.NATIVE_BUFFERS memory model.

Parameters:

src - The array from which doubles are to be read. Must be non null.

srcPos - The offset within src of the first double to be read; must be non-negative and less than src.length

destPos - The offset in the Buffer where you want to copy data to. Must be non-negative and less than getBufferSize()

length - The number of doubles to be read from src; must be non-negative and no larger than src.length - srcPos

Throws:

NullPointerException - if src is null.

IndexOutOfBoundsException - if the preconditions on the arguments mentioned above are not honored.

BufferOverflowException - if there is insufficient space in this Buffer.

get

public void get(int srcPos,
                double[] dest,
                int destPos,
                int length)

Absolute bulk get method.

This method transfers doubles from this Buffer into the given dest array. If there are fewer doubles in the Buffer starting at position srcPos than are required to satisfy the request, then no doubles are transferred and a BufferUnderflowException is thrown.

This method is equivalent to calling getByteBuffer(int, int) yourself and reading the bytes out, but is more efficient in the JNIMemoryManager.MemoryModel.NATIVE_BUFFERS memory model.

Parameters:

srcPos - The offset in the Buffer where you want to start copying data from. Must be non-negative and less than getBufferSize()

dest - The array to which doubles are to be written. Must be non null.

destPos - The offset within dest of the first double to be written; must be non-negative and less than dest.length

length - The number of doubles to be copied into dest; must be non-negative and no larger than dest.length - destPos

Throws:

NullPointerException - if dest is null.

IndexOutOfBoundsException - if the preconditions on the arguments mentioned above are not honored.

BufferOverflowException - if there is insufficient data in this Buffer to satisfy the request.

put

public void put(float[] src,
                int srcPos,
                int destPos,
                int length)

Absolute bulk put method.

This method transfers floats into this buffer from the given source array. If there are more floats to be copied from the array than there is space remaining at the specified destination offset, then no floats are transferred and a java.nio.BufferOverflowException is thrown.

This method is equivalent to calling getByteBuffer(int, int) yourself and copying the bytes over, but is more efficient in the JNIMemoryManager.MemoryModel.NATIVE_BUFFERS memory model.

Parameters:

src - The array from which floats are to be read. Must be non null.

srcPos - The offset within src of the first float to be read; must be non-negative and less than src.length

destPos - The offset in the Buffer where you want to copy data to. Must be non-negative and less than getBufferSize()

length - The number of floats to be read from src; must be non-negative and no larger than src.length - srcPos

Throws:

NullPointerException - if src is null.

IndexOutOfBoundsException - if the preconditions on the arguments mentioned above are not honored.

BufferOverflowException - if there is insufficient space in this Buffer.

get

public void get(int srcPos,
                float[] dest,
                int destPos,
                int length)

Absolute bulk get method.

This method transfers floats from this Buffer into the given dest array. If there are fewer floats in the Buffer starting at position srcPos than are required to satisfy the request, then no floats are transferred and a BufferUnderflowException is thrown.

This method is equivalent to calling getByteBuffer(int, int) yourself and reading the bytes out, but is more efficient in the JNIMemoryManager.MemoryModel.NATIVE_BUFFERS memory model.

Parameters:

srcPos - The offset in the Buffer where you want to start copying data from. Must be non-negative and less than getBufferSize()

dest - The array to which floats are to be written. Must be non null.

destPos - The offset within dest of the first float to be written; must be non-negative and less than dest.length

length - The number of floats to be copied into dest; must be non-negative and no larger than dest.length - destPos

Throws:

NullPointerException - if dest is null.

IndexOutOfBoundsException - if the preconditions on the arguments mentioned above are not honored.

BufferOverflowException - if there is insufficient data in this Buffer to satisfy the request.

put

public void put(char[] src,
                int srcPos,
                int destPos,
                int length)

Absolute bulk put method.

This method transfers chars into this buffer from the given source array. If there are more chars to be copied from the array than there is space remaining at the specified destination offset, then no chars are transferred and a java.nio.BufferOverflowException is thrown.

This method is equivalent to calling getByteBuffer(int, int) yourself and copying the bytes over, but is more efficient in the JNIMemoryManager.MemoryModel.NATIVE_BUFFERS memory model.

Parameters:

src - The array from which chars are to be read. Must be non null.

srcPos - The offset within src of the first char to be read; must be non-negative and less than src.length

destPos - The offset in the Buffer where you want to copy data to. Must be non-negative and less than getBufferSize()

length - The number of chars to be read from src; must be non-negative and no larger than src.length - srcPos

Throws:

NullPointerException - if src is null.

IndexOutOfBoundsException - if the preconditions on the arguments mentioned above are not honored.

BufferOverflowException - if there is insufficient space in this Buffer.

get

public void get(int srcPos,
                char[] dest,
                int destPos,
                int length)

Absolute bulk get method.

This method transfers chars from this Buffer into the given dest array. If there are fewer chars in the Buffer starting at position srcPos than are required to satisfy the request, then no chars are transferred and a BufferUnderflowException is thrown.

This method is equivalent to calling getByteBuffer(int, int) yourself and reading the bytes out, but is more efficient in the JNIMemoryManager.MemoryModel.NATIVE_BUFFERS memory model.

Parameters:

srcPos - The offset in the Buffer where you want to start copying data from. Must be non-negative and less than getBufferSize()

dest - The array to which chars are to be written. Must be non null.

destPos - The offset within dest of the first char to be written; must be non-negative and less than dest.length

length - The number of chars to be copied into dest; must be non-negative and no larger than dest.length - destPos

Throws:

NullPointerException - if dest is null.

IndexOutOfBoundsException - if the preconditions on the arguments mentioned above are not honored.

BufferOverflowException - if there is insufficient data in this Buffer to satisfy the request.

getByteBuffer

public ByteBuffer getByteBuffer(int offset,
                                int length)

Returns up to length bytes, starting at offset in the underlying buffer we're managing.

The buffer position, mark are initialized to zero and limit is set to the maximum capacity of this buffer. For some Buffer contents, the actual usable data in this buffer will be less that the limit.

If you want to control exactly when the underlying memory beyind the returned ByteBuffer is released, use getByteBuffer(int, int, java.util.concurrent.atomic.AtomicReference).

See Also:

getByteBuffer(int, int, java.util.concurrent.atomic.AtomicReference)

getByteBuffer

public ByteBuffer getByteBuffer(int offset,
                                int length,
                                AtomicReference<JNIReference> referenceReturn)

Returns up to length bytes, starting at offset in the underlying buffer we're managing, and also passed back a JNIReference that can optionally be used by the caller to free the underlying native memory.

The buffer position, mark are initialized to zero and limit is set to the maximum capacity of this buffer. For some Buffer contents, the actual usable data in this buffer will be less that the limit.

If you use this method you are accessing the direct native memory associated with this buffer. That means changes you make to this buffer are immediately reflected in the underlying memory.

Once you call this method, the underlying native memory allocated will not be released until all references to the returned ByteBuffer are no longer reachable and at least one call to JNIMemoryManager.gc() has been performed. You can force the memory to be collect earlier by using the JNIReference value returned when you call this method.

The JNIMemoryManager.gc() is called whenever Humble Video tries to allocate new memory for any Humble interface, so normally you don't need to care about this. If for some reason no other Humble object is ever allocated, every Humble object has a finalizer as well that will do the right thing.

You can also start up a separate thread to do continuously do Ferry garabage collections by calling JNIMemoryManager.startCollectionThread(). This thread will only wake up when it has work to do, so the overhead is very low. We don't turn it on by default since in 99.999% of cases you don't need to worry about it.

Parameters:

offset - The offset (in bytes) into the buffer managed by this Buffer

length - The requested length (in bytes) you want to access. The buffer returned may actually be longer than length.

referenceReturn - If non null, on exit calling AtomicReference.get() on this value will return a JNIReference you can use for explicitly de-allocating the underlying native store of the ByteBuffer. Call JNIReference.delete() to do that. Warning: if you do call JNIReference.delete() on the value returned in this parameter, then the returned byte buffer will be immediately invalid.

Returns:

A java.nio.ByteBuffer that directly accesses the native memory this Buffer manages, or null if error.

toString

public String toString()

Prints the same as Object.toString() but appends the maximum number of bytes that will fit in this Buffer, the type of the Buffer, and the maximum size in units of Buffer.Type that will fit in the Buffer.

Overrides:

toString in class Object

getBufferSize

public int getBufferSize()

Get the current maximum number of bytes that can
be safely placed in this buffer.

Returns:

Maximum number of bytes this buffer can manage.

make

public static Buffer make(RefCounted requestor,
                          int bufferSize)

Allocate a new buffer of at least bufferSize.

Parameters:

requestor - An optional value telling the Buffer class what object requested it. This is used for debugging memory leaks; it's a marker for the FERRY object (e.g. IPacket) that actually requested the buffer. If you're not an FERRY object, pass in null here.

bufferSize - The minimum buffer size you're requesting in bytes; a buffer with a larger size may be returned.

Returns:

A new buffer, or null on error.

getType

public Buffer.Type getType()

Get the type this buffer was created as.

A type is really just a hint. Like
java.nio.ByteBuffer objects,
Buffer objects can be cast to and from any type.

Returns:

the type

setType

public void setType(Buffer.Type type)

Reset the buffer type to a new type.

This method does not do any data conversion, it
just changes the reported type (so changing from
Type#BUFFER_UINT8 to Type#BUFFER_SINT16
is really just a "cast" operation).

Parameters:

type - the type to set to.

getTypeSize

public static int getTypeSize(Buffer.Type type)

Returns the size, in bytes, of elements of given Type.

Returns:

the size in bytes.

getSize

public int getSize()

Returns the size, in units of #getType() of
this buffer.

Returns:

number of items of type #getType() that
will fit in this buffer.

make

public static Buffer make(RefCounted requestor,
                          Buffer.Type type,
                          int numElements,
                          boolean zero)

Allocate a new buffer of at least bufferSize.

Parameters:

requestor - An optional value telling the Buffer class what object requested it. This is used for debugging memory leaks; it's a marker for the FERRY object (e.g. IPacket) that actually requested the buffer. If you're not an FERRY object, pass in null here.

type - The type of buffer.

numElements - The minimum number of elements of the specified
type you will put in this buffer.

zero - If true, we will guarantee the buffer contains
only zeros. If false, we will not (it is
faster to not, but then the buffer will have
garbage-data in it).

Returns:

A new buffer, or null on error.

getByteArray

public byte[] getByteArray(int offset,
                           int length)

Returns up to length bytes, starting at offset in the
underlying buffer we're managing.

This method COPIES the data into the byte array being
returned..

If you don't NEED the direct access that getByteBuffer
offers (and most programs can in fact take the performance
hit of the copy), we recommend you use this method.
It's much harder to accidentally leave native memory lying
around waiting for cleanup then.

Parameters:

offset - The offset (in bytes) into the buffer managed by this Buffer

length - The requested length (in bytes) you want to access. The buffer returned may
actually be longer than length.

Returns:

A copy of the data that is in this Buffer, or null
if error.

make

public static Buffer make(RefCounted requestor,
                          byte[] buffer,
                          int offset,
                          int length)

Allocate a new Buffer, and copy the data in buffer into
the new Buffer object.

Parameters:

requestor - An optional value telling the Buffer class
what object requested it. This is used for debugging memory leaks;
it's a marker for the FERRY object (e.g. IPacket) that actually
requested the buffer. If you're not an FERRY object, pass in null here.

buffer - A java byte buffer for the data containing the
data you want to copy.

offset - The starting offset in buffer where you want
to start copying.

length - The total number of bytes you want to copy from buffer.

Returns:

a new Buffer object with a copy of the data in buffer,
or null on failure.

make

public static Buffer make(RefCounted requestor,
                          ByteBuffer directByteBuffer,
                          int offset,
                          int length)

Create a new Buffer object that uses the direct byte buffer
passed in by reference (i.e. it directly uses the bytes in
the direct byte buffer).

Parameters:

requestor - An optional value telling the Buffer class
what object requested it. This is used for debugging memory leaks;
it's a marker for the FERRY object (e.g. IPacket) that actually
requested the buffer. If you're not an FERRY object, pass in null here.

directByteBuffer - A direct java.nio.ByteBuffer object
you want to use for your memory. This must be a direct object --
non direct objects will result in an JVM-dependent exception
being thrown.

offset - The starting offset in directByteBuffer where you want
to start copying.

length - The total number of bytes you want to copy from
directByteBuffer.

Returns:

a new Buffer object that is using directByteBuffer
behind the scenes, or null on failure.