add java tutorial (#2491)

java/tutorial/src/main/java/org/ray/exercise/Exercise01.java

@@ -0,0 +1,47 @@
+package org.ray.exercise;
+
+import java.io.Serializable;
+import org.ray.api.Ray;
+import org.ray.api.RayObject;
+import org.ray.api.RayRemote;
+import org.ray.core.RayRuntime;
+
+/**
+ * Define a remote function, and execute multiple remote functions in parallel.
+ */
+public class Exercise01 implements Serializable {
+
+  /**
+   * A plain remote function.
+   */
+  // `@RayRemote` annotation converts a normal function to a remote function.
+  @RayRemote
+  public static String sayHello() {
+    String ret = "hello";
+    System.out.println(ret);
+    return ret;
+  }
+
+  @RayRemote
+  public static String sayWorld() {
+    String ret = "world!";
+    System.out.println(ret);
+    return ret;
+  }
+
+  public static void main(String[] args) throws Exception {
+    try {
+      // Use `Ray.init` to initialize the Ray runtime.
+      Ray.init();
+      // Use `Ray.call` to call a remote function.
+      RayObject<String> hello = Ray.call(Exercise01::sayHello);
+      RayObject<String> world = Ray.call(Exercise01::sayWorld);
+      System.out.println("First remote call result:" + hello.get());
+      System.out.println("Second remote call result:" + world.get());
+    } catch (Throwable t) {
+      t.printStackTrace();
+    } finally {
+      RayRuntime.getInstance().cleanUp();
+    }
+  }
+}

java/tutorial/src/main/java/org/ray/exercise/Exercise02.java

@@ -0,0 +1,54 @@
+package org.ray.exercise;
+
+import org.ray.api.Ray;
+import org.ray.api.RayObject;
+import org.ray.api.RayRemote;
+import org.ray.core.RayRuntime;
+
+/**
+ * Execute remote functions in parallel with some dependencies.
+ */
+public class Exercise02 {
+
+  @RayRemote
+  public static String sayHello() {
+    String ret = "hello";
+    System.out.println(ret);
+    return ret;
+  }
+
+  @RayRemote
+  public static String sayWorld() {
+    String ret = "world!";
+    System.out.println(ret);
+    return ret;
+  }
+
+  /**
+   * A remote function with dependency.
+   */
+  @RayRemote
+  public static String merge(String hello, String world) {
+    return hello + "," + world;
+  }
+
+  public static String sayHelloWorld() {
+    RayObject<String> hello = Ray.call(Exercise02::sayHello);
+    RayObject<String> world = Ray.call(Exercise02::sayWorld);
+    // Pass unfinished results as the parameters to another remote function.
+    return Ray.call(Exercise02::merge, hello, world).get();
+  }
+
+  public static void main(String[] args) throws Exception {
+    try {
+      Ray.init();
+      String helloWorld = Exercise02.sayHelloWorld();
+      System.out.println(helloWorld);
+      assert helloWorld.equals("hello,world!");
+    } catch (Throwable t) {
+      t.printStackTrace();
+    } finally {
+      RayRuntime.getInstance().cleanUp();
+    }
+  }
+}

java/tutorial/src/main/java/org/ray/exercise/Exercise03.java

@@ -0,0 +1,45 @@
+package org.ray.exercise;
+
+import org.ray.api.Ray;
+import org.ray.api.RayObject;
+import org.ray.api.RayRemote;
+import org.ray.core.RayRuntime;
+
+/**
+ * Call a remote function from within another remote function.
+ */
+public class Exercise03 {
+
+  /**
+   * A remote function which will call another remote function.
+   */
+  @RayRemote
+  public static String sayHelloWithWorld() {
+    String ret = "hello";
+    System.out.println(ret);
+    RayObject<String> world = Ray.call(Exercise03::sayWorld);
+    return ret + "," + world.get();
+  }
+
+  /**
+   * A remote function which will be called by another remote function.
+   */
+  @RayRemote
+  public static String sayWorld() {
+    String ret = "world!";
+    System.out.println(ret);
+    return ret;
+  }
+
+  public static void main(String[] args) throws Exception {
+    try {
+      Ray.init();
+      String helloWithWorld = Ray.call(Exercise03::sayHelloWithWorld).get();
+      System.out.println(helloWithWorld);
+    } catch (Throwable t) {
+      t.printStackTrace();
+    } finally {
+      RayRuntime.getInstance().cleanUp();
+    }
+  }
+}

java/tutorial/src/main/java/org/ray/exercise/Exercise04.java

@@ -0,0 +1,74 @@
+package org.ray.exercise;
+
+import org.ray.api.Ray;
+import org.ray.api.RayList;
+import org.ray.api.RayObject;
+import org.ray.api.RayRemote;
+import org.ray.api.WaitResult;
+import org.ray.core.RayRuntime;
+
+/**
+ * Use Ray.wait to ignore stragglers
+ */
+public class Exercise04 {
+
+  @RayRemote
+  public static String f1() {
+    String ret = "f1";
+    System.out.println(ret);
+    return ret;
+  }
+
+  @RayRemote
+  public static String f2() {
+    String ret = "f2";
+    System.out.println(ret);
+    return ret;
+  }
+
+  /**
+   * A slow remote function.
+   */
+  @RayRemote
+  public static String f3() {
+    String ret = "f3";
+    try {
+      Thread.sleep(5000L);
+    } catch (Exception e) {
+      e.printStackTrace();
+    }
+    System.out.println(ret);
+    return ret;
+  }
+
+  public static void main(String[] args) throws Exception {
+    try {
+      Ray.init();
+      RayObject<String> o1 = Ray.call(Exercise04::f1);
+      RayObject<String> o2 = Ray.call(Exercise04::f2);
+      RayObject<String> o3 = Ray.call(Exercise04::f3);
+      RayList<String> rayList = new RayList<>();
+      rayList.add(o1);
+      rayList.add(o2);
+      rayList.add(o3);
+      // Ray.wait will block until specified number of results are ready
+      // or specified timeout have passed.
+      // In this case, the result of f3 will be ignored.
+      WaitResult<String> waitResult = Ray.wait(rayList, 2, 3000);
+      RayList<String> readyOnes = waitResult.getReadyOnes();
+      RayList<String> remainOnes = waitResult.getRemainOnes();
+      System.out.println("Number of readyOnes: " + readyOnes.size());
+      for (int i = 0; i < readyOnes.size(); i++) {
+        System.out.println("The value of readyOnes " + i + " is " + readyOnes.get(i));
+      }
+      System.out.println("Number of remainOnes: " + remainOnes.size());
+      for (int i = 0; i < remainOnes.size(); i++) {
+        System.out.println("The value of remainOnes " + i + " is " + remainOnes.get(i));
+      }
+    } catch (Throwable t) {
+      t.printStackTrace();
+    } finally {
+      RayRuntime.getInstance().cleanUp();
+    }
+  }
+}

java/tutorial/src/main/java/org/ray/exercise/Exercise05.java

@@ -0,0 +1,38 @@
+package org.ray.exercise;
+
+import org.ray.api.Ray;
+import org.ray.api.RayRemote;
+import org.ray.api.returns.MultipleReturns2;
+import org.ray.api.returns.RayObjects2;
+import org.ray.core.RayRuntime;
+
+/**
+ * Use multiple heterogeneous return values
+ * Java worker support at most four heterogeneous return values,
+ * To call such remote functions, use {@code Ray.call_X} as follows.
+ */
+public class Exercise05 {
+
+  public static void main(String[] args) {
+    try {
+      Ray.init();
+      RayObjects2<Integer, String> refs = Ray.call_2(Exercise05::sayMultiRet);
+      Integer obj1 = refs.r0().get();
+      String obj2 = refs.r1().get();
+      System.out.println(obj1);
+      System.out.println(obj2);
+    } catch (Throwable t) {
+      t.printStackTrace();
+    } finally {
+      RayRuntime.getInstance().cleanUp();
+    }
+  }
+
+  /**
+   * A remote function that returns multiple heterogeneous values.
+   */
+  @RayRemote
+  public static MultipleReturns2<Integer, String> sayMultiRet() {
+    return new MultipleReturns2<Integer, String>(123, "123");
+  }
+}

java/tutorial/src/main/java/org/ray/exercise/Exercise06.java

@@ -0,0 +1,46 @@
+package org.ray.exercise;
+
+import java.util.ArrayList;
+import java.util.List;
+import org.ray.api.Ray;
+import org.ray.api.RayList;
+import org.ray.api.RayObject;
+import org.ray.api.RayRemote;
+import org.ray.core.RayRuntime;
+
+/**
+ * Show usage of RayList.
+ * RayList is a list of {@code RayObject}s, inherited from {@code List}.
+ * It can be used as the type for both return values and parameters.
+ *
+ */
+public class Exercise06 {
+
+  public static void main(String[] args) {
+    try {
+      Ray.init();
+      // The result is a `RayList`.
+      RayList<Integer> ns = Ray.call_n(Exercise06::sayList, 10, 10);
+      for (int i = 0; i < 10; i++) {
+        RayObject<Integer> obj = ns.Get(i);
+        System.out.println(obj.get());
+      }
+    } catch (Throwable t) {
+      t.printStackTrace();
+    } finally {
+      RayRuntime.getInstance().cleanUp();
+    }
+  }
+
+  /**
+   * A remote function that returns a list.
+   */
+  @RayRemote
+  public static List<Integer> sayList(Integer count) {
+    ArrayList<Integer> rets = new ArrayList<>();
+    for (int i = 0; i < count; i++) {
+      rets.add(i);
+    }
+    return rets;
+  }
+}

java/tutorial/src/main/java/org/ray/exercise/Exercise07.java

@@ -0,0 +1,48 @@
+package org.ray.exercise;
+
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.Map;
+import org.ray.api.Ray;
+import org.ray.api.RayMap;
+import org.ray.api.RayObject;
+import org.ray.api.RayRemote;
+import org.ray.core.RayRuntime;
+
+/**
+ * Show usage of RayMap.
+ * {@code RayMap} is a map of {@code RayObject}s, inherited from {@code Map}.
+ * It can be used as the type for both return values and parameters.
+ */
+public class Exercise07 {
+
+  public static void main(String[] args) {
+    try {
+      Ray.init();
+      RayMap<Integer, String> ns = Ray.call_n(Exercise07::sayMap,
+          Arrays.asList(1, 2, 4, 3), "n_futures_");
+      for (Map.Entry<Integer, RayObject<String>> ne : ns.EntrySet()) {
+        Integer key = ne.getKey();
+        RayObject<String> obj = ne.getValue();
+        System.out.println(obj.get());
+      }
+    } catch (Throwable t) {
+      t.printStackTrace();
+    } finally {
+      RayRuntime.getInstance().cleanUp();
+    }
+  }
+
+  /**
+   * A remote function that returns a map.
+   */
+  @RayRemote()
+  public static Map<Integer, String> sayMap(Collection<Integer> ids, String prefix) {
+    Map<Integer, String> ret = new HashMap<>();
+    for (int id : ids) {
+      ret.put(id, prefix + id);
+    }
+    return ret;
+  }
+}

java/tutorial/src/main/java/org/ray/exercise/Exercise08.java

@@ -0,0 +1,48 @@
+package org.ray.exercise;
+
+import org.ray.api.Ray;
+import org.ray.api.RayActor;
+import org.ray.api.RayObject;
+import org.ray.api.RayRemote;
+import org.ray.core.RayRuntime;
+
+/**
+ * Show usage of actors.
+ */
+public class Exercise08 {
+
+  public static void main(String[] args) {
+    try {
+      Ray.init();
+      // `Ray.create` creates an actor instance.
+      RayActor<Adder> adder = Ray.create(Adder.class);
+      // Use `Ray.call(actor, parameters)` to call an actor method.
+      RayObject<Integer> result1 = Ray.call(Adder::add, adder, 1);
+      RayObject<Integer> result2 = Ray.call(Adder::add, adder, 10);
+      System.out.println(result1.get());
+      System.out.println(result2.get());
+    } catch (Throwable t) {
+      t.printStackTrace();
+    } finally {
+      RayRuntime.getInstance().cleanUp();
+    }
+  }
+
+  /**
+   * An example actor.
+   */
+  // `@RayRemote` annotation also converts a normal class to an actor.
+  @RayRemote
+  public static class Adder {
+
+    public Adder() {
+      sum = 0;
+    }
+
+    public Integer add(Integer n) {
+      return sum += n;
+    }
+
+    private Integer sum;
+  }
+}