Implementation:Ray project Ray Ray Actor Remote

Knowledge Sources	Ray Ray Actors
Domains	Distributed_Computing, Actor_Model
Last Updated	2026-02-13 17:00 GMT

Overview

Concrete tool for creating remote actor instances on cluster worker nodes provided by the Ray Java SDK.

Description

Ray.actor() creates an ActorCreator builder, and calling .remote() on it schedules the actor's constructor on a remote worker. Internally, Ray.actor() is defined on RayCall with overloaded variants for constructors with 0 to 6 parameters. ActorCreator.remote() delegates to Ray.internal().createActor(func, args, options), which dispatches through AbstractRayRuntime.createActor() → NativeTaskSubmitter.createActor() (JNI).

The ActorCreator builder allows fluent configuration via .setName(), .setMaxRestarts(), .setJvmOptions(), .setRuntimeEnv(), and other options before calling .remote().

Usage

Use Ray.actor() to create a new actor from a constructor reference. Chain configuration methods on the ActorCreator before calling .remote() to customize the actor's resource requirements, name, restart policy, and other options.

Code Reference

Source Location

• Repository: ray-project/ray
• File: java/api/src/main/java/io/ray/api/RayCall.java (actor factory methods, L1311-2089)
• File: java/api/src/main/java/io/ray/api/call/ActorCreator.java (L1-61)
• File: java/api/src/main/java/io/ray/api/options/ActorCreationOptions.java (L1-295)

Signature

// Factory method (on RayCall, inherited by Ray) — 0-param and 1-param variants
public static <A> ActorCreator<A> actor(RayFunc0<A> f)
public static <A, T0> ActorCreator<A> actor(RayFunc1<T0, A> f, T0 t0)
// ... up to 6 constructor parameters

// ActorCreator builder methods
public ActorCreator<A> setName(String name)
public ActorCreator<A> setMaxRestarts(int maxRestarts)
public ActorCreator<A> setMaxConcurrency(int maxConcurrency)
public ActorCreator<A> setJvmOptions(List<String> jvmOptions)
public ActorCreator<A> setLifetime(ActorLifetime lifetime)
public ActorCreator<A> setResources(Map<String, Double> resources)

// Submit actor creation
public ActorHandle<A> remote()

Import

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

I/O Contract

Inputs

Name	Type	Required	Description
f	RayFuncN<..., A>	Yes	Constructor method reference for the actor class
args	T0, T1, ...	Depends on arity	Constructor arguments
name	String	No	Name for the actor (enables lookup via Ray.getActor())
maxRestarts	int	No	Maximum number of automatic restarts on failure
lifetime	ActorLifetime	No	DETACHED (survives creator) or NON_DETACHED (default)
resources	Map<String, Double>	No	Resource requirements (e.g., CPU, GPU)

Outputs

Name	Type	Description
handle	ActorHandle<A>	A serializable handle to the remote actor, used for method invocation

Usage Examples

Basic Actor Creation

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

public class ActorCreationExample {
    public static class Counter {
        private int value = 0;
        public int increment() { return ++value; }
    }

    public static void main(String[] args) {
        Ray.init();

        // Create a remote actor
        ActorHandle<Counter> counter = Ray.actor(Counter::new).remote();

        Ray.shutdown();
    }
}

Named Actor with Options

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

public class NamedActorExample {
    public static class Cache {
        private java.util.Map<String, String> data = new java.util.HashMap<>();

        public void put(String key, String value) { data.put(key, value); }
        public String get(String key) { return data.get(key); }
    }

    public static void main(String[] args) {
        Ray.init();

        // Create a named actor with restart policy
        ActorHandle<Cache> cache = Ray.actor(Cache::new)
            .setName("global-cache")
            .setMaxRestarts(3)
            .remote();

        Ray.shutdown();
    }
}

Related Pages

Implements Principle

• Principle:Ray_project_Ray_Actor_Instance_Creation

Requires Environment

• Environment:Ray_project_Ray_Java_Build_Environment