Top Description Fields Constructors Methods
org.python.core.buffer

public abstract Class BaseNIOBuffer

extends Base1DBuffer
Class Inheritance
Known Direct Subclasses
org.python.core.buffer.SimpleNIOBuffer, org.python.core.buffer.Strided1DNIOBuffer
Imports
java.nio.BufferOverflowException, .ByteBuffer, .ReadOnlyBufferException, org.python.core.PyBUF, .PyException
Base implementation of the Buffer API for when the storage implementation is 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.

Field Summary

Modifier and TypeField and Description
protected ByteBuffer
storage

A java.nio.ByteBuffer (possibly a direct buffer) wrapping the storage that the exporter is sharing with the consumer.

Inherited from org.python.core.buffer.Base1DBuffer:
ONEZERO

Constructor Summary

AccessConstructor and Description
protected
BaseNIOBuffer(ByteBuffer
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.

storage, int
bit pattern that specifies the features allowed
featureFlags, int
index into storage of item[0]
index0, int
number of elements in the view
size, int
byte-index step between successive elements
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.

Method Summary

Modifier and TypeMethod and Description
protected byte
byteAtImpl(int
byte-index of location to retrieve
byteIndex)

Implements abstract org.python.core.buffer.BaseBuffer.byteAtImpl.

Retrieve the byte at the given index in the underlying storage treated as a flat sequence of bytes.

public int
byteIndex(int...
n-dimensional item-index from consumer
indices)

Overrides org.python.core.buffer.BaseBuffer.byteIndex.

Implements org.python.core.PyBuffer.byteIndex.

Convert a multi-dimensional item index to an absolute byte index in the storage shared by the exporter.

public void
copyFrom(byte[]
source byte array
src, int
location in source of first byte to copy
srcPos, int
starting item-index in the destination (i.e. this)
destIndex, int
number of items to copy in
count)

Overrides org.python.core.buffer.BaseBuffer.copyFrom.

Implements org.python.core.PyBuffer.copyFrom.

Copy from a slice of a (Java) byte array into the buffer starting at a given destination item-index.

protected void
copyFrom(ByteBuffer
source ByteBuffer
src, int
starting item-index in the destination (i.e. this)
destIndex, int
number of items to copy in
count)

Copy a specified number of items from a ByteBuffer into this buffer at a particular location.

public void
copyTo(int
starting item-index in the source buffer
srcIndex, byte[]
destination byte array
dest, int
byte-index in the destination array of the source item [0,...]
destPos, int
number of items to copy
count)

Overrides org.python.core.buffer.BaseBuffer.copyTo.

Implements org.python.core.PyBuffer.copyTo.

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.

public void
copyTo(ByteBuffer
destination buffer
dest)

Copy all items in this buffer into a ByteBuffer, starting at its current position.

protected void
copyTo(int
index of the first item to copy
srcIndex, ByteBuffer
destination buffer
dest, int
number of items to copy
count)

Copy a specified number of items from a particular location in this buffer into a ByteBuffer, starting at its current position.

public PyBuffer.Pointer
getBuf()

Overrides org.python.core.buffer.BaseBuffer.getBuf.

Implements org.python.core.PyBuffer.getBuf.

References Deprecated PyBuffer.Pointer is deprecated or references (maybe indirectly) at least one deprecated element.

Return a structure describing the slice of a byte array that holds the data being exported to the consumer.

protected ByteBuffer
getNIOByteBufferImpl()

Implements abstract org.python.core.buffer.BaseBuffer.getNIOByteBufferImpl.

Create a new java.nio.ByteBuffer on the underlying storage, such that positioning this buffer to a particular byte using byteIndex(int) or byteIndex(int[]) positions it at the first byte of the item so indexed.

protected void
storeAtImpl(byte
to store
value, int
byte-index of location to retrieve
byteIndex)

Implements abstract org.python.core.buffer.BaseBuffer.storeAtImpl.

Store the byte at the given index in the underlying storage treated as a flat sequence of bytes.

Inherited from org.python.core.buffer.Base1DBuffer:
calcGreatestIndexcalcLeastIndexgetLengetSizeisContiguous

Field Detail

storageback to summary
protected ByteBuffer storage

A java.nio.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 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.

Constructor Detail

BaseNIOBufferback to summary
protected BaseNIOBuffer(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. Also specify the navigation ( 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 checkRequestFlags(int) passing the consumer's request flags.

Parameters
storage:ByteBuffer

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:int

bit pattern that specifies the features allowed

index0:int

index into storage of item[0]

size:int

number of elements in the view

stride:int

byte-index step between successive elements

Method Detail

byteAtImplback to summary
protected byte byteAtImpl(int byteIndex) throws IndexOutOfBoundsException

Implements abstract org.python.core.buffer.BaseBuffer.byteAtImpl.

Doc from org.python.core.buffer.BaseBuffer.byteAtImpl.

Retrieve the byte at the given index in the underlying storage treated as a flat sequence of bytes. This byte-index will have been computed from the item index (which may have been multi-dimensional), taking into account index0, shape, 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.

Parameters
byteIndex:int

byte-index of location to retrieve

Returns:byte

the byte at byteIndex

Annotations
@Override

byteIndexback to summary
public int byteIndex(int... indices) throws IndexOutOfBoundsException

Overrides org.python.core.buffer.BaseBuffer.byteIndex.

Implements org.python.core.PyBuffer.byteIndex.

Doc from org.python.core.PyBuffer.byteIndex.

Convert a multi-dimensional item index to an absolute byte index in the storage shared by the exporter. The storage exported as a 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 byteAt(int...) and the byte-index (as used with the ByteBuffer returned by getNIOByteBuffer()).

Parameters
indices:int[]

n-dimensional item-index from consumer

Returns:int

corresponding byte-index in actual storage

Annotations
@Override

copyFromback to summary
public void copyFrom(byte[] src, int srcPos, int destIndex, int count) throws IndexOutOfBoundsException, PyException

Overrides org.python.core.buffer.BaseBuffer.copyFrom.

Implements org.python.core.PyBuffer.copyFrom.

Doc from org.python.core.buffer.BaseBuffer.copyFrom.

Copy from a slice of a (Java) byte array into the buffer starting at a given destination item-index. This may validly be done only for a one-dimensional buffer, as the meaning of the destination index is not otherwise defined. 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.

Parameters
src:byte[]

Doc from org.python.core.PyBuffer.copyFrom.

source byte array

srcPos:int

Doc from org.python.core.PyBuffer.copyFrom.

location in source of first byte to copy

destIndex:int

Doc from org.python.core.PyBuffer.copyFrom.

starting item-index in the destination (i.e. this)

count:int

Doc from org.python.core.PyBuffer.copyFrom.

number of items to copy in

Annotations
@Override
Exceptions
IndexOutOfBoundsException:

Doc from org.python.core.PyBuffer.copyFrom.

if access out of bounds in source or destination

PyException:

Doc from org.python.core.PyBuffer.copyFrom.

TypeError if read-only buffer

copyFromback to summary
protected void copyFrom(ByteBuffer src, int destIndex, int count) throws IndexOutOfBoundsException, PyException

Copy a specified number of items from a ByteBuffer into this buffer at a particular location.

Parameters
src:ByteBuffer

source ByteBuffer

destIndex:int

starting item-index in the destination (i.e. this)

count:int

number of items to copy in

Exceptions
IndexOutOfBoundsException:
if access out of bounds in source or destination
PyException:
TypeError if read-only buffer
copyToback to summary
public void copyTo(int srcIndex, byte[] dest, int destPos, int count) throws IndexOutOfBoundsException

Overrides org.python.core.buffer.BaseBuffer.copyTo.

Implements org.python.core.PyBuffer.copyTo.

Doc from org.python.core.buffer.BaseBuffer.copyTo.

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. 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.

Parameters
srcIndex:int

Doc from org.python.core.PyBuffer.copyTo.

starting item-index in the source buffer

dest:byte[]

Doc from org.python.core.PyBuffer.copyTo.

destination byte array

destPos:int

Doc from org.python.core.PyBuffer.copyTo.

byte-index in the destination array of the source item [0,...]

count:int

Doc from org.python.core.PyBuffer.copyTo.

number of items to copy

Annotations
@Override
Exceptions
IndexOutOfBoundsException:

Doc from org.python.core.PyBuffer.copyTo.

if access out of bounds in source or destination

copyToback to summary
public void copyTo(ByteBuffer dest) throws BufferOverflowException, ReadOnlyBufferException

Copy all items in this buffer into a ByteBuffer, starting at its current position.

Parameters
dest:ByteBuffer

destination buffer

copyToback to summary
protected void copyTo(int srcIndex, ByteBuffer dest, int count) throws BufferOverflowException, ReadOnlyBufferException, IndexOutOfBoundsException

Copy a specified number of items from a particular location in this buffer into a ByteBuffer, starting at its current position. .

Parameters
srcIndex:int

index of the first item to copy

dest:ByteBuffer

destination buffer

count:int

number of items to copy

getBufback to summary
public PyBuffer.Pointer getBuf()

Overrides org.python.core.buffer.BaseBuffer.getBuf.

Implements org.python.core.PyBuffer.getBuf.

Doc from org.python.core.PyBuffer.getBuf.

References Deprecated

PyBuffer.Pointer is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

Return a structure describing the slice of a byte array that holds the data being exported to the consumer. For a one-dimensional contiguous buffer, assuming the following client code where 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.

Returns:PyBuffer.Pointer

structure defining the byte[] slice that is the shared data

Annotations
@SuppressWarnings:deprecation
@Override

getNIOByteBufferImplback to summary
protected ByteBuffer getNIOByteBufferImpl()

Implements abstract org.python.core.buffer.BaseBuffer.getNIOByteBufferImpl.

Doc from org.python.core.buffer.BaseBuffer.getNIOByteBufferImpl.

Create a new java.nio.ByteBuffer on the underlying storage, such that positioning this buffer to a particular byte using byteIndex(int) or byteIndex(int[]) positions it at the first byte of the item so indexed.

Annotations
@Override
storeAtImplback to summary
protected void storeAtImpl(byte value, int byteIndex) throws PyException

Implements abstract org.python.core.buffer.BaseBuffer.storeAtImpl.

Doc from org.python.core.buffer.BaseBuffer.storeAtImpl.

Store the byte at the given index in the underlying storage treated as a flat sequence of bytes. This byte-index will have been computed from the item index (which may have been multi-dimensional), taking into account index0, shape, 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.

Parameters
value:byte

to store

byteIndex:int

byte-index of location to retrieve

Annotations
@Override
Exceptions
PyException:
BufferError if this object is read-only.