Merge pull request #1162 from beehive-lab/docs/offheap_types

Update the documentation

docs/source/conf.py

@@ -6,8 +6,8 @@
 copyright = "2013-2023, APT Group, Department of Computer Science"
 author = "The University of Manchester"
 
-release = "v0.16"
-version = "v0.16.0"
+release = "v1.0"
+version = "v1.0"
 
 # -- General configuration
 

docs/source/index.rst

@@ -26,8 +26,8 @@ Contents
    introduction
    installation
    simple-start
-   offheap-types
    programming
+   offheap-types
    truffle-languages
    profiler
    benchmarking

docs/source/offheap-types.rst

@@ -1,6 +1,6 @@
-Transitioning from v0.15 to v0.16
+Migrating from v0.15.2 to v1.0
 ==================================
-Starting from v0.16, TornadoVM is providing its custom off-heap data types. Below is a list of the new types, with an arrow pointing from the on-heap primitive array types to their off-heap equivalent.
+Starting from v1.0, TornadoVM is providing its custom off-heap data types. Below is a list of the new types, with an arrow pointing from the on-heap primitive array types to their off-heap equivalent.
 
 * ``int[]`` -> ``IntArray``
 * ``float[]`` -> ``FloatArray``
@@ -14,7 +14,7 @@ The existing Matrix and Vector collection types that TornadoVM offers (e.g., ``V
 
 1. Off-heap types API
 -------------------------
-The new off-heap types encapsulate a `Memory Segment <https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/foreign/MemorySegment.html>`_, a contiguous region of memory outside the Java heap. To allocate off-heap memory, each type offers two constructors. The first has only one argument, the number of elements that the Memory Segment will contain. Through the second constructor, the values of a primitive array can be provided for the initialization of the segment.
+The new off-heap types encapsulate a `Memory Segment <https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/foreign/MemorySegment.html>`_, a contiguous region of memory outside the Java heap. To allocate off-heap memory using the TornadoVM API, each type offers a constructor with one argument that indicates the number of elements that the Memory Segment will contain.
 
 E.g.:
 
@@ -23,41 +23,49 @@ E.g.:
    // allocate an off-heap memory segment that will contain 16 int values
    IntArray intArray = new IntArray(16);
 
-   // allocate an off-heap memory segment that is initialized with the four float values in the constructor
-   FloatArray floatArray = new FloatArray(new float[] {0.0f, 0.1f, 0.2.f, 0.3f});
+Additionally, developers can create an instance of a TornadoVM native array by invoking factory methods for different data representations. In the following examples we will demonstrate the API functions for the ``FloatArray`` type, but the same methods apply for all support native array types. 
 
-The main methods that the off-heap types expose to manage the Memory Segment of each type are presented in the list below. In each signature, ``X`` is the equivalent primitive type, e.g., for the methods of the ``IntArray`` class, ``X`` is ``int``.
+.. code:: java
+
+   // from on-heap array to TornadoVM native array
+   public static FloatArray fromArray(float[] values);
+   // from individual items to TornadoVM native array
+   public static FloatArray fromElements(float... values);
+   // from Memory Segment to TornadoVM native array
+   public static FloatArray fromSegment(MemorySegment segment); 
+
+The main methods that the off-heap types expose to manage the Memory Segment of each type are presented in the list below. 
 
 .. code:: java
 
-   * public void set(int index, X value) // sets a value at a specific index
+   public void set(int index, float value) // sets a value at a specific index
       E.g.:
           FloatArray floatArray = new FloatArray(16);
           floatArray.set(0, 10.0f); // at index 0 the value is 10.0f
-   * public X get(int index) // returns the value of a specific index
+   public float get(int index) // returns the value of a specific index
       E.g.:
-          DoubleArray doubleArray = new DoubleArray(new double[] {2.4, 1.4, 2.5, 5.1});
-          double doubleValue = doubleArray.get(3); // returns 5.1
-   * public void clear() // sets the values of the segment to 0
+          FloatArray floatArray = FloatArray.fromArray(new float[] {2.0f, 1.0f, 2.0f, 5.0f});
+          float floatValue = floatArray.get(3); // returns 5.0f
+   public void clear() // sets the values of the segment to 0
       E.g.:
-          IntArray intArray = new IntArray(1024);
-          intArray.clear(); // the intArray contains 1024 zeros
-   * public void init(X value) // initializes the segment with a specific value
+          FloatArray floatArray = new FloatArray(1024);
+          floatArray.clear(); // the floatArray contains 1024 zeros
+   public void init(float value) // initializes the segment with a specific value
       E.g.:
-   	  IntArray intArray = new IntArray(1024);
-          intArray.init(1); // // the intArray contains 1024 ones
-   * public int getSize() // returns the number of elements in the segment
+   	  FloatArray floatArray = new FloatArray(1024);
+          floatArray.init(1.0f); // the floatArray contains 1024 ones
+   public int getSize() // returns the number of elements in the segment
       E.g.:
           FloatArray floatArray = new FloatArray(16);
           int size = floatArray.getSize(); // returns 16
-   * public static XArray fromElements(X... values); // creates a new instance of the type and initializes it with a set of values
-      E.g.:
-          IntArray intArray = IntArray.fromElements(1,2,3,4,5,6,7,8);  // new IntArray initialized with the values in the parameter list
-
+   public float[] toHeapArray(); // Converts the data from off-heap to on-heap
+   public long getNumBytesOfSegment(); // Returns the total number of bytes the underlying Memory Segment occupies, including the header bytes
+   public long getNumBytesWithoutHeader(); // Returns the total number of bytes the underlying Memory Segment occupies, excluding the header bytes
+   
 **NOTE:** The methods ``init()`` and ``clear()`` are essential because, contrary to their counterpart primitive arrays which are initialized by default with 0, the new types contain garbage values when first created.
 
-2. Example: Transforming an existing TornadoVM program
--------------------------------------------------------
+2. Example: Migrating TornadoVM applications from <= 0.15.2 to 1.0
+-------------------------------------------------------------------
 
 Below is an example of a TornadoVM program that uses primitive arrays: