Add Javadoc and document the examples in TornadoVM

[jjfumero]

Add Javadoc to document the examples in TornadoVM.

This affects the packages under the examples module:

https://github.com/beehive-lab/TornadoVM/tree/master/tornado-examples/src/main/java/uk/ac/manchester/tornado/examples

The documentation is at the class-level and it will contain a description of how the TornadoVM API is used for each example. Additionally, it contains how to run the example from the command line.

This class contains an example of documentation of what we are looking for:

https://github.com/beehive-lab/TornadoVM/blob/master/tornado-examples/src/main/java/uk/ac/manchester/tornado/examples/polyglot/HelloPython.java#L26-L38

Summary

• Javadoc at the class-level
• High-level description of the problem/example
• Description of the TornadoVM API calls used and how are they composed
• How to run from the command line.

[luisa-poeschl]

Hi! I could try to do that, if you'd like 😄

[stratika]

Hi @luisa01-code, that would be very nice. Feel free to open a PR, thank you.

[aaronms1]

Here is an example I wrote using "hover over links" when the Jdoc is rendered on the ArrayAccInt example class. Having the docs linked in this matter will have "pop-ups" when a user clicks, or hovers over them from any other class that mentions the original, pointing back at its Jdoc::

/**

• {@link ArrayAccInt} is an example that demonstrates how to use the Tornado framework
• to parallelize a computation on an array of integers.
• How to run?

• tornado -m tornado.examples/uk.ac.manchester.tornado.examples.arrays.ArrayAccInt
  

*/ public class ArrayAccInt {

/**
 * {@link ArrayAccInt#acc} that takes an array of integers and a value as input.
 * It uses the Tornado "@Parallel" annotation to indicate that the loop in the method should be parallelized.
 * The loop iterates over the array and adds the value to each element.
 * @param a int[]
 * @param value int
 */
public static void acc(int[] a, int value) {
    for (@Parallel int i = 0; i < a.length; i++) {
        a[i] += value;
    }
}

/**
 * {@link ArrayAccInt#main(String[])} creates an array of integers and fills it with the value 10.
 * It then creates a TaskGraph object, which represents a computation that can be executed in parallel.
 * The array is transferred to the device (e.g., GPU) using the "transferToDevice" method.
 * <p>
 *     Next, a loop is used to create a number of tasks that call the {@link ArrayAccInt#acc} method.
 *     Each task operates on the same array but with a different value. The tasks are added to the TaskGraph.
 * <p>
 *     Finally, the array is transferred back to the host (e.g., CPU) using the "transferToHost" method.
 *     The TaskGraph is then converted into an ImmutableTaskGraph, which is used to create a TornadoExecutionPlan.
 *     The plan is executed using the "execute" method.
 * <p>
 *     After the execution, the example prints the contents of the array.
 *     The expected result is the initial value of 10 for each element plus the number of tasks (8) that were executed
 * </p>
 * @param args int[]
 */
public static void main(String[] args) {

    final int numElements = 8;
    final int numKernels = 8;
    int[] a = new int[numElements];

    Arrays.fill(a, 10);

    TaskGraph taskGraph = new TaskGraph("s0");
    taskGraph.transferToDevice(DataTransferMode.FIRST_EXECUTION, a);
    for (int i = 0; i < numKernels; i++) {
        taskGraph.task("t" + i, ArrayAccInt::acc, a, 1);
    }
    taskGraph.transferToHost(DataTransferMode.EVERY_EXECUTION, a);

    ImmutableTaskGraph immutableTaskGraph = taskGraph.snapshot();
    TornadoExecutionPlan executor = new TornadoExecutionPlan(immutableTaskGraph);
    executor.execute();

    System.out.println("a: " + Arrays.toString(a));
}

}

[aaronms1]

I realize the example doc is a lot smaller, but it doesn't go into detail. If the devs at TornadoVM would like more Jdocs like the above, feel free to reach out.

[jjfumero]

Hi @aaronms1 , thanks for your interest in TornadoVM and aim for contributing to the project. Yes, that is something close to what we are looking for. However, we are currently changing interfaces and some parts of the APIs. so please, hold on until we have the next release (0.16), which is planned for the end of the year because the data management will change. We are currently integrating with the Panama API (for offering off-heap data types to developers and applying more optimizations between the CPU and the GPU regarding data migration and data transfers).

Additionally, we are in the latest phase of arrangement with the University about the contributor agreement, and we believe this will be available soon.

[aaronms1]

that's great news!! Let me know if I can contribute in any other ways. I'd be happy to help.

Has any one attempted to utilize tornodoVM on web apps? I'm in the process of doing so, and was wondering if anyone would be interested in helping me accomplish this? I believe tornado can make an impact with all the high end GPU accelerated servers in high demand, and being built. Ill be joining the slack channel soon to ask there as well.