Jython 2.7.4 · org.python.core.buffer.BaseBuffer · APIdia, the JavaDoc alternative

Base implementation of the Buffer API providing variables and accessors for the navigation arrays, methods for expressing and checking the buffer request flags, methods and mechanism for get-release counting, boilerplate error checks and their associated exceptions, and default implementations of some methods for access to the buffer content. The design aim is to ensure unglamorous common code need only be implemented once.

This class leaves undefined the storage mechanism for the bytes (typically byte[] or java.nio.ByteBuffer), while remaining definite that it is an indexable sequence of bytes. A concrete class that extends this one must provide elementary accessors byteAtImpl(int), storeAtImpl(byte, int) that abstract this storage, a factory getNIOByteBufferImpl() for ByteBuffers that wrap the storage, and a factory for slices getBufferSlice(int, int, int, int).

The sub-class constructor must specify the feature flags (see BaseBuffer(int, int, int[], int[])), set index0, shape and strides, and finally check the client capabilities with checkRequestFlags(int). A sub-class intended to represent slices of an exporter that counts its exports, as part of a locking protocol like bytearray's, must override getRoot() so that a call to release() on a view of slice, propagates to the buffer view that provided the slice.

Access methods provided here necessarily work with the abstracted byteAtImpl(int), storeAtImpl(byte, int) interface, but subclasses are able to override them with more efficient versions that employ knowledge of the particular storage type used.

This base implementation is writable only if PyBUF#WRITABLE is in the feature flags passed to the constructor. Otherwise, all methods for write access raise a TypeError and isReadonly() returns true. However, a client intending to write should have presented PyBUF#WRITABLE in its client request flags when getting the buffer, and been prevented by a BufferError exception at that point.

At the time of writing, only one-dimensional buffers of item size one are used in the Jython core.

Modifier and Type	Field and Description
protected int	exports Count the number of times `release()` must be called before actual release actions need to take place.
private int	gFeatureFlags Bit pattern using the constants defined in `PyBUF` that records the actual features this buffer offers.
protected int	index0 Absolute byte-index in the storage of `item[0]`.
protected BufferProtocol	obj The object that exported this buffer (or `null` if the subclass or exporter chooses not to supply a reference).
protected int[]	shape The dimensions of the array represented by the buffer.
protected int[]	strides Step sizes in the underlying buffer essential to correct translation of an index (or indices) into an index into the storage.

Access	Constructor and Description
protected	BaseBuffer(int bit pattern that specifies the features allowed featureFlags, int index into storage of `item[0,...,0]` index0, int[] elements in each dimension shape, int[] between successive elements in each dimension strides) Construct an instance of `BaseBuffer` in support of a sub-class, specifying the 'feature flags', or at least a starting set to be adjusted later.

Method Summary

Modifier and Type	Method and Description
protected final void	addFeatureFlags(int to set within the feature flags flags) Add to the features of this buffer expressed using the constants defined in `PyBUF`, setting individual flags specified while leaving those already set.
private static PyException	Returns: PyException (BufferError) specifying the mis-match bufferErrorFromSyndrome(int of the mis-match between buffer and requested features syndrome) General purpose method to construct an exception to throw according to the syndrome.
protected static PyException	Returns: the error as a PyException bufferIsNot(String property) Convenience method to create (for the caller to throw) a `BufferError("underlying buffer is not {property}")`.
protected static PyException	Returns: the error as a PyException bufferReleased(String name of operation or null operation) Convenience method to create (for the caller to throw) a `BufferError("{operation} operation forbidden on released buffer object")`.
protected static PyException	Returns: the error as a PyException bufferRequires(String feature) Convenience method to create (for the caller to throw) a `BufferError("buffer structure requires consumer to use {feature}")`.
public byte	byteAt(int to retrieve from index) Implements org.python.core.PyBuffer.byteAt. Return the byte indexed from a one-dimensional buffer with item size one.
public byte	byteAt(int... specifying location to retrieve from indices) Implements org.python.core.PyBuffer.byteAt. Return the byte indexed from an N-dimensional buffer with item size one.
protected abstract byte	Returns: the byte at byteIndex byteAtImpl(int byte-index of location to retrieve byteIndex) Retrieve the byte at the given index in the underlying storage treated as a flat sequence of bytes.
public int	byteIndex(int item-index from consumer index) Implements org.python.core.PyBuffer.byteIndex. Convert an item index (for a one-dimensional buffer) to an absolute byte index in the storage shared by the exporter.
public int	byteIndex(int... n-dimensional item-index from consumer indices) Implements org.python.core.PyBuffer.byteIndex. Convert a multi-dimensional item index to an absolute byte index in the storage shared by the exporter.
protected int	Returns: greatest absolute index in storage calcGreatestIndex() Calculate the absolute byte index in the storage array of the last item of the exported data (if we are not using indirection).
protected int	Returns: least absolute index in storage calcLeastIndex() Calculate the absolute byte index in the storage array of the first item of the exported data (if we are not using indirection).
pack-priv int	Returns: number of dimensions checkDimension(int[] into the buffer (to test) indices) Check the number of indices (but not their values), raising a Python BufferError if this does not match the number of dimensions.
pack-priv void	checkDimension(int number of dimensions being assumed by caller n) Check that the number offered is in fact the number of dimensions in this buffer, raising a Python BufferError if this does not match the number of dimensions.
protected void	checkHasArray() Check that the buffer is backed by an array the client can access as byte[].
protected void	checkRequestFlags(int capabilities of and navigation assumed by the consumer flags) General purpose method to check the consumer request flags (typically the argument to `BufferProtocol#getBuffer(int)`) against the feature flags (see `getFeatureFlags()`) that characterise the features of the buffer, and to raise an exception (Python `BufferError`) with an appropriate message in the case of a mismatch.
protected void	checkWritable() Check that the buffer is writable.
public void	close() Implements org.python.core.PyBuffer.close. An alias for `release()` to satisfy `AutoCloseable`.
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) 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.
public void	copyFrom(PyBuffer source buffer src) Implements org.python.core.PyBuffer.copyFrom. Copy the whole of another `PyBuffer` into this buffer.
public void	copyTo(byte[] destination byte array dest, int byte-index in the destination array of the byte [0] destPos) Implements org.python.core.PyBuffer.copyTo. Copy the contents of the buffer to the destination byte array.
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) 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.
protected static PyException	Returns: the error as a PyException differentStructure() Convenience method to create (for the caller to throw) a `ValueError("buffer ...`
public PyBuffer.Pointer	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.
public synchronized PyBuffer	getBuffer(int specifying features demanded and the navigational capabilities of the consumer flags) Implements org.python.core.PyBuffer.getBuffer. Method by which the consumer requests the buffer from the exporter.
public synchronized BaseBuffer	getBufferAgain(int flags) Allow an exporter to re-use this object again even if it has been "finally" released.
public PyBuffer	getBufferSlice(int specifying features demanded and the navigational capabilities of the consumer flags, int index in the current buffer start, int number of items in the required slice count) Implements org.python.core.PyBuffer.getBufferSlice. Equivalent to `getBufferSlice(int, int, int, int)` with stride 1.
protected final int	Returns: capabilities of and navigation required by the exporter/buffer getFeatureFlags() Get the features of this buffer expressed using the constants defined in `PyBUF`.
public String	getFormat() Implements org.python.core.PyBuffer.getFormat. A format string in the language of Python structs describing how the bytes of each item should be interpreted.
public int	getItemsize() Implements org.python.core.PyBUF.getItemsize. The number of bytes stored in each indexable item.
public int	getLen() Implements org.python.core.PyBUF.getLen. The total number of bytes represented by the view, which will be the product of the elements of the `shape` array, and the item size in bytes.
public int	getNdim() Implements org.python.core.PyBUF.getNdim. The number of dimensions to the buffer.
public ByteBuffer	getNIOByteBuffer() Implements org.python.core.PyBuffer.getNIOByteBuffer. Obtain a `java.nio.ByteBuffer` giving access to the bytes that hold the data being exported by the original object.
protected abstract ByteBuffer	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.
public final BufferProtocol	getObj() Implements org.python.core.PyBuffer.getObj. Return the underlying exporting object (or `null` if no object implementing the `BufferProtocol` is in that role).
public PyBuffer.Pointer	getPointer(int in the buffer to position the pointer index) Implements org.python.core.PyBuffer.getPointer. References Deprecated `PyBuffer.Pointer` is deprecated or references (maybe indirectly) at least one deprecated element. Return a structure describing the position in a byte array of a single item from the data being exported to the consumer.
public PyBuffer.Pointer	getPointer(int... multidimensional index at which to position the pointer indices) Implements org.python.core.PyBuffer.getPointer. References Deprecated `PyBuffer.Pointer` is deprecated or references (maybe indirectly) at least one deprecated element. Return a structure describing the position in a byte array of a single item from the data being exported to the consumer, in the case that array may be multi-dimensional.
protected PyBuffer	Returns: this buffer (or the root buffer if this is a sliced view) getRoot() Some `PyBuffer`s, those created by slicing a `PyBuffer`, are related to a root `PyBuffer`.
public int[]	getShape() Implements org.python.core.PyBUF.getShape. An array reporting the size of the buffer, considered as a multidimensional array, in each dimension and (by its length) giving the number of dimensions.
protected int	getSize()
public int[]	getStrides() Implements org.python.core.PyBUF.getStrides. The `strides` array gives the distance in the storage array between adjacent items (in each dimension).
public int[]	getSuboffsets() Implements org.python.core.PyBUF.getSuboffsets. The `suboffsets` array is a further part of the support for interpreting the buffer as an n-dimensional array of items, where the array potentially uses indirect addressing (like a real Java array of arrays, in fact).
public boolean	hasArray() Implements org.python.core.PyBuffer.hasArray. Report whether the exporter is able to offer direct access to the exported storage as a Java byte array (through the API that involves class `Pointer`), or only supports the abstract API.
public int	intAt(int to retrieve from index) Implements org.python.core.PyBuffer.intAt. Return the unsigned byte value indexed from a one-dimensional buffer with item size one.
public int	intAt(int... specifying location to retrieve from indices) Implements org.python.core.PyBuffer.intAt. Return the unsigned byte value indexed from an N-dimensional buffer with item size one.
private boolean	isCContiguous()
public boolean	isContiguous(char 'C', 'F' or 'A', as the storage order is C, Fortran or either. order) Implements org.python.core.PyBUF.isContiguous. Enquire whether the array is represented contiguously in the backing storage, according to C or Fortran ordering.
private boolean	isFortranContiguous()
public boolean	isReadonly() Implements org.python.core.PyBUF.isReadonly. Determine whether the consumer is entitled to write to the exported storage.
public boolean	isReleased() Implements org.python.core.PyBuffer.isReleased. True only if the buffer has been released with (the required number of calls to) `release()` or some equivalent operation.
protected static PyException	Returns: the error as a PyException notWritable() Convenience method to create (for the caller to throw) a `TypeError("cannot modify read-only memory")`.
public void	release() Implements org.python.core.PyBuffer.release. A buffer is (usually) a view onto to the internal state of an exporting object, and that object may have to restrict its behaviour while the buffer exists.
protected void	releaseAction() This method will be called when the number of calls to `release()` on this buffer is equal to the number of calls to `PyBuffer#getBuffer(int)` and to `BufferProtocol#getBuffer(int)` that returned this buffer.
protected final void	removeFeatureFlags(int to clear within the feature flags flags) Remove features from this buffer expressed using the constants defined in `PyBUF`, clearing individual flags specified while leaving others already set.
protected final void	setFeatureFlags(int new value for the feature flags flags) Set the features of this buffer expressed using the constants defined in `PyBUF`, replacing any previous set.
public void	storeAt(byte to store value, int to location index) Implements org.python.core.PyBuffer.storeAt. Store the given byte at the indexed location in of a one-dimensional buffer with item size one.
public void	storeAt(byte to store value, int... specifying location to store at indices) Implements org.python.core.PyBuffer.storeAt. Store the given byte at the indexed location in of an N-dimensional buffer with item size one.
protected abstract void	storeAtImpl(byte to store value, int byte-index of location to retrieve byteIndex) Store the byte at the given index in the underlying storage treated as a flat sequence of bytes.
public String	toString() Overrides java.lang.Object.toString. Implements org.python.core.PyBuffer.toString. The toString() method of a buffer reproduces the values in the buffer (as unsigned integers) as the character codes of a `String`.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

public abstract Class BaseBuffer

Field Summary

Constructor Summary

Method Summary