Principle:Ray project Ray Actor Class Definition
| Knowledge Sources | |
|---|---|
| Domains | Distributed_Computing, Actor_Model |
| Last Updated | 2026-02-13 17:00 GMT |
Overview
A design pattern for defining stateful computation units whose constructor serves as a remote factory and whose public methods serve as remotely invocable operations.
Description
In the Actor Model, an actor is a stateful entity that processes messages sequentially. In Ray's Java SDK, actors are defined as standard Java classes — no special annotations or base classes are required. The class constructor becomes the actor factory (invoked remotely during actor creation), and public methods become remotely callable operations. State is maintained in instance fields across method calls.
This is a user-defined pattern, not a library API. The user writes a plain Java class, and Ray's runtime machinery handles remote instantiation, method dispatch, and state isolation.
Usage
Define an actor class when you need stateful computation that persists across multiple remote method calls. Actors are appropriate for maintaining counters, caches, model weights, database connections, or any mutable state that must be accessed sequentially from a distributed context.
Theoretical Basis
The actor model (Hewitt, Bishop & Steiger, 1973) defines actors as fundamental units of computation that:
- Process one message at a time (sequential consistency)
- Maintain private state
- Can send messages to other actors
- Can create new actors
In Ray, these properties map to:
- Sequential consistency: Actor methods execute one at a time (unless concurrency groups are configured)
- Private state: Instance fields are isolated per actor process
- Messaging: Method invocations via handle.task() are the message-passing mechanism
- Actor creation: Actors can create other actors via Ray.actor()
Requirements for actor classes:
// Pseudo-code pattern for a valid actor class
class MyActor {
// Private state
private StateType state;
// Constructor = actor factory (parameters become creation arguments)
public MyActor(ConstructorArgs...) {
this.state = initializeState(args);
}
// Public methods = remotely callable operations
public ReturnType operation(MethodArgs...) {
// Can read/modify state
return result;
}
}