Module tornado.api
Package uk.ac.manchester.tornado.api.types.arrays

Class ByteArray

java.lang.Object
uk.ac.manchester.tornado.api.types.arrays.TornadoNativeArray
uk.ac.manchester.tornado.api.types.arrays.ByteArray
public final class ByteArray extends TornadoNativeArray
ByteArray relies on preview features of the Java platform:
Programs can only use ByteArray when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
This class represents an array of bytes stored in native memory. The byte data is stored in a MemorySegmentPREVIEW, which represents a contiguous region of off-heap memory. The class also encapsulates methods for setting and getting byte values, for initializing the byte array, and for converting the array to and from different representations.

  • Constructor Details

    • ByteArray

      public ByteArray(int numberOfElements)
      Constructs a new instance of the ByteArray that will store a user-specified number of elements.
      Parameters:
      numberOfElements - The number of elements in the array.

    • ByteArray

      public ByteArray(ByteArray... arrays)
      Constructs a new ByteArray instance by concatenating the contents of the given array of ByteArray instances.
      Parameters:
      arrays - An array of ByteArray instances to be concatenated into the new instance.

  • Method Details

    • fromArray

      public static ByteArray fromArray(byte[] values)
      Creates a new instance of the ByteArray class from an on-heap byte array.
      Parameters:
      values - The on-heap byte array to create the instance from.
      Returns:
      A new ByteArray instance, initialized with values of the on-heap byte array.

    • fromElements

      public static ByteArray fromElements(byte... values)
      Creates a new instance of the ByteArray class from a set of byte values.
      Parameters:
      values - The byte values to initialize the array with.
      Returns:
      A new ByteArray instance, initialized with the given values.

    • fromSegment

      public static ByteArray fromSegment(MemorySegmentPREVIEW segment)
      Creates a new instance of the ByteArray class from a MemorySegmentPREVIEW.
      Parameters:
      segment - The MemorySegmentPREVIEW containing the off-heap byte data.
      Returns:
      A new ByteArray instance, initialized with the segment data.

    • fromSegmentShallow

      public static ByteArray fromSegmentShallow(MemorySegmentPREVIEW segment)
      Creates a new instance of the ByteArray class by wrapping an existing MemorySegmentPREVIEW without copying its contents.
      Parameters:
      segment - The MemorySegmentPREVIEW containing *both* the off-heap byte *header* and *data*.
      Returns:
      A new ByteArray instance that wraps the given segment.

    • fromByteBuffer

      public static ByteArray fromByteBuffer(ByteBuffer buffer)
      Creates a new instance of the ByteArray class from a ByteBuffer.
      Parameters:
      buffer - The ByteBuffer containing the float data.
      Returns:
      A new ByteArray instance, initialized with the buffer data.

    • toHeapArray

      public byte[] toHeapArray()
      Converts the byte data from off-heap to on-heap, by copying the values of a ByteArray instance into a new on-heap array.
      Returns:
      A new on-heap byte array, initialized with the values stored in the ByteArray instance.

    • set

      public void set(int index, byte value)
      Sets the byte value at a specified index of the ByteArray instance.
      Parameters:
      index - The index at which to set the byte value.
      value - The byte value to store at the specified index.

    • setHalfFloat

      public void setHalfFloat(int byteIndex, HalfFloat value)
      Sets the half-float value at the specified byte index within the ByteArray instance. The specified byteIndex must be aligned to a 2-byte boundary; if it is not, an IllegalArgumentException will be thrown. The method internally calculates the appropriate short index for storage and updates the underlying memory segment.
      Parameters:
      byteIndex - The byte index at which to set the half-float value. Must be aligned to a 2-byte boundary.
      value - The HalfFloat value to be stored at the specified index.
      Throws:
      IllegalArgumentException - If the byteIndex is not aligned to a 2-byte boundary.

    • get

      public byte get(int index)
      Gets the byte value stored at the specified index of the ByteArray instance.
      Parameters:
      index - The index of which to retrieve the byte value.
      Returns:
      en element byte of the off-heap array

    • getHalfFloat

      public HalfFloat getHalfFloat(int byteIndex)
      Gets the half-float value stored at the specified byte index within the ByteArray instance. The specified byteIndex must be aligned to a 2-byte boundary; if it is not, an IllegalArgumentException will be thrown. The method internally calculates the appropriate short index for storage and retrieves the value from the underlying memory segment.
      Parameters:
      byteIndex - The byte index from which to retrieve the half-float value. Must be aligned to a 2-byte boundary.
      Returns:
      A HalfFloat instance containing the value stored at the specified index.
      Throws:
      IllegalArgumentException - If the byteIndex is not aligned to a 2-byte boundary.

    • clear

      public void clear()
      Sets all the values of the ByteArray instance to zero.
      Specified by:
      clear in class TornadoNativeArray

    • getElementSize

      public int getElementSize()
      Specified by:
      getElementSize in class TornadoNativeArray

    • init

      public void init(byte value)
      Initializes all the elements of the ByteArray instance with a specified value.
      Parameters:
      value - The byte value to initialize the ByteArray instance with.

    • getSize

      public int getSize()
      Description copied from class: TornadoNativeArray
      Returns the number of elements stored in the native array.
      Specified by:
      getSize in class TornadoNativeArray
      Returns:
      Returns the number of byte elements stored in the ByteArray instance.

    • getSegment

      public MemorySegmentPREVIEW getSegment()
      Returns the underlying MemorySegmentPREVIEW of the ByteArray instance.
      Specified by:
      getSegment in class TornadoNativeArray
      Returns:
      The MemorySegmentPREVIEW associated with the ByteArray instance.

    • getSegmentWithHeader

      public MemorySegmentPREVIEW getSegmentWithHeader()
      Returns the underlying MemorySegmentPREVIEW of the ByteArray instance, including the header.
      Specified by:
      getSegmentWithHeader in class TornadoNativeArray
      Returns:
      The MemorySegmentPREVIEW associated with the ByteArray instance.

    • getNumBytesOfSegmentWithHeader

      public long getNumBytesOfSegmentWithHeader()
      Returns the total number of bytes that the MemorySegmentPREVIEW, associated with the ByteArray instance, occupies.
      Specified by:
      getNumBytesOfSegmentWithHeader in class TornadoNativeArray
      Returns:
      The total number of bytes of the MemorySegmentPREVIEW.

    • getNumBytesOfSegment

      public long getNumBytesOfSegment()
      Returns the number of bytes of the MemorySegmentPREVIEW that is associated with the ByteArray instance, excluding the header bytes.
      Specified by:
      getNumBytesOfSegment in class TornadoNativeArray
      Returns:
      The number of bytes of the raw data in the MemorySegmentPREVIEW.

    • initialize

      public static void initialize(ByteArray array, byte value)
      Factory method to initialize a ByteArray. This method can be invoked from a Task-Graph.
      Parameters:
      array - Input Array.
      value - The float value to initialize the ByteArray instance with.

    • concat

      public static ByteArray concat(ByteArray... arrays)
      Concatenates multiple ByteArray instances into a single ByteArray.
      Parameters:
      arrays - Variable number of ByteArray objects to be concatenated.
      Returns:
      A new ByteArray instance containing all the elements of the input arrays, concatenated in the order they were provided.

    • slice

      public ByteArray slice(int offset, int length)
      Extracts a slice of elements from a given ByteArray, creating a new ByteArray instance.
      Parameters:
      offset - The starting index from which to begin the slice, inclusive.
      length - The number of elements to include in the slice.
      Returns:
      A new ByteArray instance representing the specified slice of the original array.
      Throws:
      IllegalArgumentException - if the specified slice is out of the bounds of the original array.