mirror of
https://github.com/vale981/ray
synced 2025-03-08 11:31:40 -05:00
130 lines
3.5 KiB
ReStructuredText
130 lines
3.5 KiB
ReStructuredText
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<R> 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<T>``.
|
|
|
|
The returned object is labeled as ``RayObject<R>`` 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 <T> RayObject<T> put(T object);
|
|
public static <T, TM> RayObject<T> put(T obj, TM metadata);
|
|
|
|
``RayObject<T>.get/getMeta``
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code:: java
|
|
|
|
public class RayObject<T> {
|
|
public T get() throws TaskExecutionException;
|
|
public <M> 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.
|
|
|
|
.. code:: java
|
|
|
|
public static WaitResult<T> wait(List<RayObject<T>> waitfor, int numReturns, int timeoutMilliseconds);
|
|
public static WaitResult<T> wait(List<RayObject<T>> waitfor, int numReturns);
|
|
public static WaitResult<T> wait(List<RayObject<T>> waitfor);
|
|
|
|
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> 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<Integer> result1 = Ray.call(Adder::add, adder, 1);
|
|
System.out.println(result1.get()); // 1
|
|
RayObject<Integer> result2 = Ray.call(Adder::add, adder, 10);
|
|
System.out.println(result2.get()); // 11
|