Implementation:Ray project Ray Ray GetActor

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

Overview

Concrete tool for retrieving handles to named actors from the Ray cluster registry provided by the Ray Java SDK.

Description

Ray.getActor() looks up a named actor in the Global Control Store (GCS) and returns an Optional<ActorHandle<T>>. The actor must have been created with .setName() in its creation options. The method supports optional namespace isolation via a second parameter. Internally, it delegates to RayNativeRuntime.getActor() which calls nativeGetActorIdOfNamedActor() via JNI.

Usage

Use Ray.getActor() to obtain a handle to a named actor from any process connected to the same Ray cluster. Check the returned Optional for presence before using the handle.

Code Reference

Source Location

• Repository: ray-project/ray
• File: java/api/src/main/java/io/ray/api/Ray.java (L186-204)
• File: java/runtime/src/main/java/io/ray/runtime/RayNativeRuntime.java (L182-193)

Signature

public static <T extends BaseActorHandle> Optional<T> getActor(String name)
public static <T extends BaseActorHandle> Optional<T> getActor(String name, String namespace)

Import

import io.ray.api.Ray;
import io.ray.api.ActorHandle;
import java.util.Optional;

I/O Contract

Inputs

Name	Type	Required	Description
name	String	Yes	The name assigned during actor creation via .setName()
namespace	String	No	Optional namespace for isolation (defaults to current namespace)

Outputs

Name	Type	Description
handle	Optional<ActorHandle<T>>	Present if the named actor exists, empty otherwise

Usage Examples

Retrieve a Named Actor

import io.ray.api.Ray;
import io.ray.api.ActorHandle;
import java.util.Optional;

public class NamedActorLookup {
    public static class Cache {
        private java.util.Map<String, String> data = new java.util.HashMap<>();
        public void put(String k, String v) { data.put(k, v); }
        public String get(String k) { return data.get(k); }
    }

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

        // Create a named actor
        Ray.actor(Cache::new).setName("shared-cache").remote();

        // Retrieve the named actor (potentially from another process)
        Optional<ActorHandle<Cache>> cacheOpt = Ray.getActor("shared-cache");
        if (cacheOpt.isPresent()) {
            ActorHandle<Cache> cache = cacheOpt.get();
            cache.task(Cache::put, "key1", "value1").remote();
        }

        Ray.shutdown();
    }
}

Related Pages

Implements Principle

• Principle:Ray_project_Ray_Named_Actor_Retrieval

Requires Environment

• Environment:Ray_project_Ray_Java_Build_Environment