Class BaseNIOBuffer

  • All Implemented Interfaces:
    java.lang.AutoCloseable, BufferProtocol, PyBUF, PyBuffer
    Direct Known Subclasses:
    SimpleNIOBuffer, Strided1DNIOBuffer

    public abstract class BaseNIOBuffer
    extends Base1DBuffer
    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.
    • Method Detail

      • byteIndex

        public int byteIndex​(int... indices)
                      throws java.lang.IndexOutOfBoundsException
        Description copied from interface: PyBuffer
        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 PyBuffer.byteAt(int...) and the byte-index (as used with the ByteBuffer returned by PyBuffer.getNIOByteBuffer()).
        Specified by:
        byteIndex in interface PyBuffer
        Overrides:
        byteIndex in class BaseBuffer
        Parameters:
        indices - n-dimensional item-index from consumer
        Returns:
        corresponding byte-index in actual storage
        Throws:
        java.lang.IndexOutOfBoundsException
      • copyTo

        public void copyTo​(int srcIndex,
                           byte[] dest,
                           int destPos,
                           int count)
                    throws java.lang.IndexOutOfBoundsException
        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.

        Specified by:
        copyTo in interface PyBuffer
        Overrides:
        copyTo in class BaseBuffer
        Parameters:
        srcIndex - starting item-index in the source buffer
        dest - destination byte array
        destPos - byte-index in the destination array of the source item [0,...]
        count - number of items to copy
        Throws:
        java.lang.IndexOutOfBoundsException - if access out of bounds in source or destination
      • copyTo

        public void copyTo​(java.nio.ByteBuffer dest)
                    throws java.nio.BufferOverflowException,
                           java.nio.ReadOnlyBufferException
        Copy all items in this buffer into a ByteBuffer, starting at its current position.
        Parameters:
        dest - destination buffer
        Throws:
        java.nio.BufferOverflowException
        java.nio.ReadOnlyBufferException
      • copyFrom

        public void copyFrom​(byte[] src,
                             int srcPos,
                             int destIndex,
                             int count)
                      throws java.lang.IndexOutOfBoundsException,
                             PyException
        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.

        Specified by:
        copyFrom in interface PyBuffer
        Overrides:
        copyFrom in class BaseBuffer
        Parameters:
        src - source byte array
        srcPos - location in source of first byte to copy
        destIndex - starting item-index in the destination (i.e. this)
        count - number of items to copy in
        Throws:
        java.lang.IndexOutOfBoundsException - if access out of bounds in source or destination
        PyException - (TypeError) if read-only buffer
      • getBuf

        public PyBuffer.Pointer getBuf()
        Description copied from interface: PyBuffer
        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.

        Specified by:
        getBuf in interface PyBuffer
        Overrides:
        getBuf in class BaseBuffer
        Returns:
        structure defining the byte[] slice that is the shared data