
public class Buffer extends RefCounted
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.
| Modifier and Type | Class and Description |
|---|---|
static class |
Buffer.Type
Types of data that are in this buffer.
|
| Constructor and Description |
|---|
Buffer(long ignore1,
boolean ignore2)
DO NOT USE THIS CONSTRUCTOR - USE
make(RefCounted,int) INSTEAD. |
| 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. |
getCurrentRefCountpublic Buffer(long ignore1,
boolean ignore2)
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.
ignore1 - ignore.ignore2 - ignore.public void delete()
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).
delete in class RefCountedpublic Buffer copyReference()
copyReference in class RefCountedpublic boolean equals(Object obj)
public int hashCode()
public void put(byte[] src,
int srcPos,
int destPos,
int length)
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.
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.lengthdestPos - 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 - srcPosNullPointerException - 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.public void get(int srcPos,
byte[] dest,
int destPos,
int length)
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.
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.lengthlength - The number of bytes to be copied into dest; must be
non-negative and no larger than dest.length - destPosNullPointerException - 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.public void put(short[] src,
int srcPos,
int destPos,
int length)
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.
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.lengthdestPos - 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 - srcPosNullPointerException - 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.public void get(int srcPos,
short[] dest,
int destPos,
int length)
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.
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.lengthlength - The number of shorts to be copied into dest; must be
non-negative and no larger than dest.length - destPosNullPointerException - 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.public void put(int[] src,
int srcPos,
int destPos,
int length)
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.
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.lengthdestPos - 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 - srcPosNullPointerException - 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.public void get(int srcPos,
int[] dest,
int destPos,
int length)
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.
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.lengthlength - The number of ints to be copied into dest; must be
non-negative and no larger than dest.length - destPosNullPointerException - 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.public void put(long[] src,
int srcPos,
int destPos,
int length)
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.
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.lengthdestPos - 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 - srcPosNullPointerException - 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.public void get(int srcPos,
long[] dest,
int destPos,
int length)
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.
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.lengthlength - The number of longs to be copied into dest; must be
non-negative and no larger than dest.length - destPosNullPointerException - 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.public void put(double[] src,
int srcPos,
int destPos,
int length)
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.
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.lengthdestPos - 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 - srcPosNullPointerException - 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.public void get(int srcPos,
double[] dest,
int destPos,
int length)
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.
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.lengthlength - The number of doubles to be copied into dest; must be
non-negative and no larger than dest.length - destPosNullPointerException - 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.public void put(float[] src,
int srcPos,
int destPos,
int length)
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.
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.lengthdestPos - 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 - srcPosNullPointerException - 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.public void get(int srcPos,
float[] dest,
int destPos,
int length)
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.
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.lengthlength - The number of floats to be copied into dest; must be
non-negative and no larger than dest.length - destPosNullPointerException - 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.public void put(char[] src,
int srcPos,
int destPos,
int length)
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.
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.lengthdestPos - 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 - srcPosNullPointerException - 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.public void get(int srcPos,
char[] dest,
int destPos,
int length)
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.
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.lengthlength - The number of chars to be copied into dest; must be
non-negative and no larger than dest.length - destPosNullPointerException - 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.public ByteBuffer getByteBuffer(int offset, int length)
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).
public ByteBuffer getByteBuffer(int offset, int length, AtomicReference<JNIReference> referenceReturn)
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.
offset - The offset (in bytes) into the buffer managed by
this Bufferlength - 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.public String toString()
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.
public int getBufferSize()
public static Buffer make(RefCounted requestor, int bufferSize)
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.public Buffer.Type getType()
A type is really just a hint. Like
java.nio.ByteBuffer objects,
Buffer objects can be cast to and from any type.
public void setType(Buffer.Type 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).
type - the type to set to.public static int getTypeSize(Buffer.Type type)
public int getSize()
public static Buffer make(RefCounted requestor, Buffer.Type type, int numElements, boolean zero)
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 specifiedzero - If true, we will guarantee the buffer containspublic byte[] getByteArray(int offset,
int length)
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.
offset - The offset (in bytes) into the buffer managed by this Bufferlength - The requested length (in bytes) you want to access. The buffer returned maypublic static Buffer make(RefCounted requestor, byte[] buffer, int offset, int length)
requestor - An optional value telling the Buffer classbuffer - A java byte buffer for the data containing theoffset - The starting offset in buffer where you wantlength - The total number of bytes you want to copy from buffer.public static Buffer make(RefCounted requestor, ByteBuffer directByteBuffer, int offset, int length)
requestor - An optional value telling the Buffer classdirectByteBuffer - A direct java.nio.ByteBuffer objectoffset - The starting offset in directByteBuffer where you wantlength - The total number of bytes you want to copy fromCopyright © 2018 Humble Software. All rights reserved.