Ray Java API ============ Basic API --------- ``Ray.init()`` ~~~~~~~~~~~~~~ ``Ray.init`` should be invoked before any other Ray functions to initialize the runtime. ``@RayRemote`` ~~~~~~~~~~~~~~ The ``@RayRemote`` annotation can be used to decorate static java methods and classes. The former indicates that a target function is a remote function, which is valid with the following requirements: - It must be a public static method. - The method must be deterministic for task reconstruction to behave correctly. When the annotation is used for a class, the class becomes an actor class (an encapsulation of state shared among many remote functions). The member functions can be invoked using ``Ray.call``. The requirements for an actor class are as follows: - It must have a constructor without any parameters. - Any inner class must be public static. - It must not have any static fields or methods, as the semantic is undefined with multiple instances of this same class on different machines. - All methods that will be invoked remotely must be ``public``. ``Ray.call`` ~~~~~~~~~~~~ ``Ray.call`` is used to invoke a remote function. .. code:: java RayObject call(Func func, ...); The parameters of ``Ray.call`` are the target method ``func``, followed by its original parameters. - The return type of ``func`` must be ``R``. - Currently at most 6 parameters of ``func`` are allowed. - Each parameter can either be the raw type ``T``, or ``RayObject``. The returned object is labeled as ``RayObject`` and its value will be put into the object store on the machine where the function call is executed. ``Ray.put`` ~~~~~~~~~~~ You can also invoke ``Ray.put`` to explicitly place an object into the object store. .. code:: java public static RayObject put(T object); public static RayObject put(T obj, TM metadata); ``RayObject.get/getMeta`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code:: java public class RayObject { public T get() throws TaskExecutionException; public M getMeta() throws TaskExecutionException; } These 2 methods will block the current thread until the requested data is locally available. ``Ray.wait`` ~~~~~~~~~~~~ ``Ray.wait`` is used to wait for a list of ``RayObject``\s to be locally available. It will block the current thread until ``numReturns`` objects are ready or ``timeoutMilliseconds`` has passed. See multi-value support for ``RayList``. .. code:: java public static WaitResult wait(RayList waitfor, int numReturns, int timeoutMilliseconds); public static WaitResult wait(RayList waitfor, int numReturns); public static WaitResult wait(RayList waitfor); Multi-value API --------------- Multi-value Types ~~~~~~~~~~~~~~~~~ Multiple ``RayObject``\s can be placed in a single data structure as a return value or as a ``Ray.call`` parameter through the following container types. ``MultipleReturnsX`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This consists of multiple heterogeneous values, with types ``R0``, ``R1``,... respectively. Currently this container type is only supported as the return type of ``Ray.call``. Therefore you cannot use it as the type of an input parameter. ``RayList`` ^^^^^^^^^^^^^^ This is a list of ``RayObject``\s, which inherits from ``List`` in Java. It can be used as the type for both a return value and a parameter value. ``RayMap`` ^^^^^^^^^^^^^^^^ A map of ``RayObject``\s with each indexed using a label with type ``L``, inherited from ``Map``. It can be used as the type for both a return value and a parameter value. Multiple heterogeneous return values ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To return multiple heterogeneous values in a remote functions, you can define your original method's return type as ``MultipleReturnsX`` and then invoke it with ``Ray.call_X``. Note: ``X`` is the number of return values, at most 4 values are supported. Here's an `example `_. Return with ``RayList`` ~~~~~~~~~~~~~~~~~~~~~~~ To return a list of ``RayObject``\s, you can invoke your method with ``Ray.call_n``. ``Ray.call_n`` is similar to ``Ray.call`` except that it has an additional parameter ``returnCount``, which specifies the number of return values in the list. Here's an `example `_. Return with ``RayMap`` ~~~~~~~~~~~~~~~~~~~~~~ This is similar to ``RayList`` case, except that now each returned ``RayObject`` in ``RayMap`` has a given label when ``Ray.call_n`` is called. Here's an `example `_. Use ``RayList`` and ``RayMap`` as parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code:: java public class ListTExample { public static void main(String[] args) { Ray.init(); RayList ints = new RayList<>(); ints.add(Ray.put(new Integer(1))); ints.add(Ray.put(new Integer(1))); ints.add(Ray.put(new Integer(1))); RayObject obj = Ray.call(ListTExample::sum，(List)ints); Assert.assertTrue(obj.get().equals(3)); } @RayRemote public static int sum(List ints) { int sum = 0; for (Integer i : ints) { sum += i; } return sum; } } Actor Support ------------- Create Actors ~~~~~~~~~~~~~ A regular class annotated with ``@RayRemote`` is an actor class. .. code:: java @RayRemote public class Adder { public Adder() { sum = 0; } public int add(int n) { return sum += n; } private int sum; } To create an actor instance, use ``Ray.create()``. .. code:: java RayActor adder = Ray.create(Adder.class); Call Actor Methods ~~~~~~~~~~~~~~~~~~ ``Ray.call`` or its extended versions (e.g., ``Ray.call_n``) are also used to call actor methods, and the actor instance must be the first parameter. .. code:: java RayObject result1 = Ray.call(Adder::add, adder, 1); System.out.println(result1.get()); // 1 RayObject result2 = Ray.call(Adder::add, adder, 10); System.out.println(result2.get()); // 11