Ray Core Walkthrough

This walkthrough will overview the core concepts of Ray:

  1. Starting Ray

  2. Using remote functions (tasks)

  3. Using remote classes (actors)

  4. Working with Ray Objects

With Ray, your code will work on a single machine and can be easily scaled to large cluster.

Java demo code in this documentation can be found here.

Installation

To run this walkthrough, install Ray with pip install -U ray. For the latest wheels (for a snapshot of master), you can use these instructions at Daily Releases (Nightlies).

To run this walkthrough, add Ray API and Ray Runtime as dependencies. Snapshot versions can be found in sonatype repository.

Note: To run your Ray Java application, you need to install Ray Python with pip install -U ray first. (For Ray Java snapshot versions, install nightly Ray Python wheels.) The versions of Ray Java and Ray Python must match.

The C++ Ray API is currently experimental with limited support and it’s not supported on Windows. You can track its development here and report issues on GitHub. Run the following commands to get started:

Install ray with C++ API support and generate a bazel project with the ray command.

pip install "ray[cpp]"
mkdir ray-template && ray cpp --generate-bazel-project-template-to ray-template

The project template comes with a simple example application. You can try this example out in 2 ways:

  1. Run the example application directly, which will start a Ray cluster locally.

cd ray-template && bash run.sh
  1. Connect the example application to an existing Ray cluster by specifying the RAY_ADDRESS env var.

ray start --head
RAY_ADDRESS=127.0.0.1:6379 bash run.sh

Now you can build your own Ray C++ application based on this project template.

Starting Ray

You can start Ray on a single machine by adding this to your code.

Note

In recent versions of Ray (>=1.5), ray.init() will automatically be called on the first use of a Ray remote API.

import ray

# Start Ray. If you're connecting to an existing cluster, you would use
# ray.init(address=<cluster-address>) instead.
ray.init()

...
import io.ray.api.Ray;

public class MyRayApp {

    public static void main(String[] args) {
        // Start Ray runtime. If you're connecting to an existing cluster, you can set
        // the `-Dray.address=<cluster-address>` java system property.
        Ray.init();
        ...
    }
}
// Run `ray cpp --show-library-path` to find headers and libraries.
#include <ray/api.h>

int main(int argc, char **argv) {
    // Start Ray runtime. If you're connecting to an existing cluster, you can set
    // the `RAY_ADDRESS` env var.
    ray::Init();
    ...
}

Ray will then be able to utilize all cores of your machine. Find out how to configure the number of cores Ray will use at Configuring Ray.

To start a multi-node Ray cluster, see the cluster setup page.

Using Tasks, Actors, and Objects

Click through below to walk through using Ray’s key concepts: Tasks, Actors, and Objects.

Tip

We suggest reading through the walkthrough for each section prior to browsing more deeply into the materials.