public abstract class BaseNIOBuffer extends Base1DBuffer
java.nio.ByteBuffer
. The description of BaseBuffer
mostly applies. Methods
provided or overridden here are appropriate to 1-dimensional arrays, of any item size, backed by
a ByteBuffer
.PyBuffer.Pointer
Modifier and Type | Field and Description |
---|---|
protected java.nio.ByteBuffer |
storage
A
ByteBuffer (possibly a direct buffer) wrapping the storage that the
exporter is sharing with the consumer. |
ONE, ZERO
ANY_CONTIGUOUS, AS_ARRAY, C_CONTIGUOUS, CONTIG, CONTIG_RO, CONTIGUITY, F_CONTIGUOUS, FORMAT, FULL, FULL_RO, INDIRECT, IS_C_CONTIGUOUS, IS_F_CONTIGUOUS, MAX_NDIM, NAVIGATION, ND, RECORDS, RECORDS_RO, SIMPLE, STRIDED, STRIDED_RO, STRIDES, WRITABLE
Modifier | Constructor and Description |
---|---|
protected |
BaseNIOBuffer(java.nio.ByteBuffer storage,
int featureFlags,
int index0,
int size,
int stride)
Construct an instance of
BaseNIOBuffer in support of a sub-class, specifying the
'feature flags', or at least a starting set to be adjusted later. |
Modifier and Type | Method and Description |
---|---|
protected byte |
byteAtImpl(int byteIndex)
Retrieve the byte at the given index in the underlying storage treated as a flat sequence of
bytes.
|
int |
byteIndex(int... indices)
Convert a multi-dimensional item index to an absolute byte index in the storage shared by the
exporter.
|
void |
copyFrom(byte[] src,
int srcPos,
int destIndex,
int count)
Copy from a slice of a (Java) byte array into the buffer starting at a given destination
item-index.
|
protected void |
copyFrom(java.nio.ByteBuffer src,
int destIndex,
int count)
Copy a specified number of items from a
ByteBuffer into this buffer at a
particular location. |
void |
copyTo(java.nio.ByteBuffer dest)
Copy all items in this buffer into a
ByteBuffer , starting at its current
position. |
void |
copyTo(int srcIndex,
byte[] dest,
int destPos,
int count)
Copy a simple slice of the buffer-view to the destination byte array, defined by a starting
item-index in the source buffer and the
count of items to copy. |
protected void |
copyTo(int srcIndex,
java.nio.ByteBuffer dest,
int count)
Copy a specified number of items from a particular location in this buffer into a
ByteBuffer , starting at its current position. |
PyBuffer.Pointer |
getBuf()
Return a structure describing the slice of a byte array that holds the data being exported to
the consumer.
|
protected java.nio.ByteBuffer |
getNIOByteBufferImpl()
Create a new
java.nio.ByteBuffer on the underlying storage, such that
positioning this buffer to a particular byte using BaseBuffer.byteIndex(int) or
BaseBuffer.byteIndex(int[]) positions it at the first byte of the item so indexed. |
protected void |
storeAtImpl(byte value,
int byteIndex)
Store the byte at the given index in the underlying storage treated as a flat sequence of
bytes.
|
calcGreatestIndex, calcLeastIndex, getLen, getSize, isContiguous
addFeatureFlags, bufferIsNot, bufferReleased, bufferRequires, byteAt, byteAt, byteIndex, checkHasArray, checkRequestFlags, checkWritable, close, copyFrom, copyTo, differentStructure, getBuffer, getBufferAgain, getBufferSlice, getFeatureFlags, getFormat, getItemsize, getNdim, getNIOByteBuffer, getObj, getPointer, getPointer, getRoot, getShape, getStrides, getSuboffsets, hasArray, intAt, intAt, isReadonly, isReleased, notWritable, release, releaseAction, removeFeatureFlags, setFeatureFlags, storeAt, storeAt, toString
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
getBufferSlice
protected java.nio.ByteBuffer storage
ByteBuffer
(possibly a direct buffer) wrapping the storage that the
exporter is sharing with the consumer. The data to be exposed may be only a subset of the
bytes in the buffer, defined by the navigation information index0
,
shape
, strides
, etc., usually defined in the constructor.
Implementations must not adjust the position and limit of storage
after
construction. It will generally be a duplicate of (not a reference to) a ByteBuffer held by
the client code. The capacity and backing store are fixed in construction, and the position
will always be BaseBuffer.index0
. The limit is always higher than any valid data, and in the
case of a contiguous buffer (with positive stride), is exactly just beyond the last item, so
that a series of ByteBuffer.get operations will yield the data.
protected BaseNIOBuffer(java.nio.ByteBuffer storage, int featureFlags, int index0, int size, int stride)
BaseNIOBuffer
in support of a sub-class, specifying the
'feature flags', or at least a starting set to be adjusted later. Also specify the navigation
( BaseBuffer.index0
, number of elements, and stride. These 'feature flags' are the features of
the buffer exported, not the flags that form the consumer's request. The buffer will be
read-only unless PyBUF.WRITABLE
is set. PyBUF.FORMAT
and
PyBUF.AS_ARRAY
are implicitly added to the feature flags.
To complete initialisation, the sub-class normally must call BaseBuffer.checkRequestFlags(int)
passing the consumer's request flags.
storage
- the ByteBuffer
wrapping the exported object state. NOTE: this
PyBuffer
keeps a reference and may manipulate the position, mark and
limit hereafter. Use ByteBuffer.duplicate()
to give it an isolated copy.featureFlags
- bit pattern that specifies the features allowedindex0
- index into storage of item[0]
size
- number of elements in the viewstride
- byte-index step between successive elementsprotected byte byteAtImpl(int byteIndex) throws java.lang.IndexOutOfBoundsException
BaseBuffer
BaseBuffer.index0
, BaseBuffer.shape
, BaseBuffer.strides
,
and the item size. The caller is responsible for validating the original item-index and
raising (typically) an IndexOutOfBoundsException
. Misuse of this method may
still result in unchecked exceptions characteristic of the storage implementation.byteAtImpl
in class BaseBuffer
byteIndex
- byte-index of location to retrievejava.lang.IndexOutOfBoundsException
protected void storeAtImpl(byte value, int byteIndex) throws PyException
BaseBuffer
BaseBuffer.index0
, BaseBuffer.shape
, BaseBuffer.strides
,
and the item size. The caller is responsible for validating the original item-index and
raising (typically) an IndexOutOfBoundsException
. Misuse of this method may
still result in unchecked exceptions characteristic of the storage implementation. This
method must implement the check for read-only character, raising a BufferError
in the case of a violation.storeAtImpl
in class BaseBuffer
value
- to storebyteIndex
- byte-index of location to retrievePyException
- BufferError
if this object is read-only.public int byteIndex(int... indices) throws java.lang.IndexOutOfBoundsException
PyBuffer
PyBuffer
is a linearly-indexed sequence of
bytes, although it may not actually be a heap-allocated Java byte[]
object. The
purpose of this method is to allow the exporter to define the relationship between the item
index (as used in PyBuffer.byteAt(int...)
and the byte-index (as used with the
ByteBuffer
returned by PyBuffer.getNIOByteBuffer()
).byteIndex
in interface PyBuffer
byteIndex
in class BaseBuffer
indices
- n-dimensional item-index from consumerjava.lang.IndexOutOfBoundsException
public void copyTo(int srcIndex, byte[] dest, int destPos, int count) throws java.lang.IndexOutOfBoundsException
count
of items to copy. This may validly
be done only for a one-dimensional buffer, as the meaning of the starting item-index is
otherwise not defined. count*itemsize
bytes will be occupied in the destination.
The default implementation in BaseBuffer
deals with the general one-dimensional
case of arbitrary item size and stride, but is unable to optimise access to sequential bytes.
The default implementation in BaseNIOBuffer
deals with the general
one-dimensional case of arbitrary item size and stride.
copyTo
in interface PyBuffer
copyTo
in class BaseBuffer
srcIndex
- starting item-index in the source bufferdest
- destination byte arraydestPos
- byte-index in the destination array of the source item [0,...]count
- number of items to copyjava.lang.IndexOutOfBoundsException
- if access out of bounds in source or destinationpublic void copyTo(java.nio.ByteBuffer dest) throws java.nio.BufferOverflowException, java.nio.ReadOnlyBufferException
ByteBuffer
, starting at its current
position.dest
- destination bufferjava.nio.BufferOverflowException
java.nio.ReadOnlyBufferException
protected void copyTo(int srcIndex, java.nio.ByteBuffer dest, int count) throws java.nio.BufferOverflowException, java.nio.ReadOnlyBufferException, java.lang.IndexOutOfBoundsException
ByteBuffer
, starting at its current position. .srcIndex
- index of the first item to copydest
- destination buffercount
- number of items to copyjava.nio.BufferOverflowException
java.nio.ReadOnlyBufferException
java.lang.IndexOutOfBoundsException
public void copyFrom(byte[] src, int srcPos, int destIndex, int count) throws java.lang.IndexOutOfBoundsException, PyException
count*itemsize
bytes will be read
from the source.
The default implementation in BaseBuffer
deals with the general one-dimensional
case of arbitrary item size and stride, but is unable to optimise access to sequential bytes.
The default implementation in BaseNIOBuffer
deals with the general
one-dimensional case of arbitrary item size and stride.
copyFrom
in interface PyBuffer
copyFrom
in class BaseBuffer
src
- source byte arraysrcPos
- location in source of first byte to copydestIndex
- starting item-index in the destination (i.e. this
)count
- number of items to copy injava.lang.IndexOutOfBoundsException
- if access out of bounds in source or destinationPyException
- TypeError
if read-only bufferprotected void copyFrom(java.nio.ByteBuffer src, int destIndex, int count) throws java.lang.IndexOutOfBoundsException, PyException
ByteBuffer
into this buffer at a
particular location.src
- source ByteBuffer
destIndex
- starting item-index in the destination (i.e. this
)count
- number of items to copy injava.lang.IndexOutOfBoundsException
- if access out of bounds in source or destinationPyException
- TypeError
if read-only bufferprotected java.nio.ByteBuffer getNIOByteBufferImpl()
BaseBuffer
java.nio.ByteBuffer
on the underlying storage, such that
positioning this buffer to a particular byte using BaseBuffer.byteIndex(int)
or
BaseBuffer.byteIndex(int[])
positions it at the first byte of the item so indexed.getNIOByteBufferImpl
in class BaseBuffer
public PyBuffer.Pointer getBuf()
PyBuffer
obj
has type BufferProtocol
:
PyBuffer a = obj.getBuffer(PyBUF.SIMPLE); int itemsize = a.getItemsize(); PyBuffer.Pointer b = a.getBuf();the item with index
k
is in the array b.storage
at index
[b.offset + k*itemsize]
to [b.offset + (k+1)*itemsize - 1]
inclusive. And if itemsize==1
, the item is simply the byte
b.storage[b.offset + k]
If the buffer is multidimensional or non-contiguous, storage[offset]
is still
the (first byte of) the item at index [0] or [0,...,0]. However, it is necessary to navigate
b.storage
using the shape
, strides
and maybe
suboffsets
provided by the API.
getBuf
in interface PyBuffer
getBuf
in class BaseBuffer