Principle:Ray project Ray Named Actor Retrieval
| Knowledge Sources | |
|---|---|
| Domains | Distributed_Computing, Service_Discovery |
| Last Updated | 2026-02-13 17:00 GMT |
Overview
A service discovery mechanism that retrieves a handle to a previously created named actor from a global registry.
Description
Named Actor Retrieval enables cross-process and cross-job access to actors by their registered name. When an actor is created with a name (via .setName() in ActorCreationOptions), it is registered in the Global Control Store (GCS). Any process connected to the same Ray cluster can retrieve a handle to that actor by name, enabling shared services, coordination, and cross-job communication.
Optional namespace isolation prevents name collisions between independent applications sharing a cluster.
Usage
Use named actor retrieval when multiple Ray jobs or processes need to share a stateful actor. This is the primary service discovery mechanism in Ray — it replaces the need for external service registries for intra-cluster communication.
Theoretical Basis
Named actor retrieval implements a naming service pattern common in distributed systems. The GCS serves as the name registry:
The lookup returns Optional.empty() if no actor with that name exists, enabling safe discovery patterns.