Implementation:Ray project Ray Actor Class Pattern

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

Overview

Interface specification for user-defined actor classes in the Ray Java actor system.

Description

Actor classes in Ray Java are standard Java classes with no special base class or annotation requirements. The runtime uses the class constructor as a factory function (passed to Ray.actor()) and dispatches method calls via handle.task(). The class must be accessible on the Ray worker classpath and its constructor must be referenceable as a RayFunc method reference.

Usage

Define a standard Java class with a public constructor and public methods. The constructor parameters become actor creation arguments, and public methods become remotely invocable operations.

Code Reference

Source Location

• Repository: ray-project/ray
• File: java/test/src/main/java/io/ray/docdemo/UsingActorsDemo.java (example actor classes)

Interface Specification

/**
 * Actor class requirements:
 * 1. Public class accessible on the Ray classpath
 * 2. Public constructor (becomes the actor factory)
 * 3. Public methods (become remotely callable operations)
 * 4. Instance fields for state (maintained across method calls)
 */
public class Counter {
    private int value;

    public Counter() {
        this.value = 0;
    }

    public Counter(int initialValue) {
        this.value = initialValue;
    }

    public int increment() {
        this.value += 1;
        return this.value;
    }

    public int getValue() {
        return this.value;
    }
}

Import

// No special imports needed for actor class definition.
// Ray imports are only needed when using the actor:
import io.ray.api.Ray;
import io.ray.api.ActorHandle;

I/O Contract

Inputs

Name	Type	Required	Description
Constructor parameters	User-defined	No	Arguments passed during actor creation via Ray.actor(Constructor, args...).remote()
Method parameters	User-defined	No	Arguments passed during actor method invocation via handle.task(Method, args...).remote()

Outputs

Name	Type	Description
Constructor	Actor instance	The newly created actor with initialized state
Methods	User-defined return type	The return value of the actor method, accessible via ObjectRef

Usage Examples

Simple Counter Actor

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

public class CounterExample {
    // Actor class definition
    public static class Counter {
        private int value = 0;

        public int increment() {
            this.value += 1;
            return this.value;
        }

        public int getValue() {
            return this.value;
        }
    }

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

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

        // Invoke methods remotely
        ObjectRef<Integer> ref1 = counter.task(Counter::increment).remote();
        ObjectRef<Integer> ref2 = counter.task(Counter::increment).remote();
        ObjectRef<Integer> ref3 = counter.task(Counter::getValue).remote();

        System.out.println(ref1.get()); // 1
        System.out.println(ref2.get()); // 2
        System.out.println(ref3.get()); // 2

        Ray.shutdown();
    }
}

Actor with Constructor Parameters

public static class InitCounter {
    private int value;

    public InitCounter(int initialValue) {
        this.value = initialValue;
    }

    public int increment() {
        return ++this.value;
    }
}

// Create with initial value of 10
ActorHandle<InitCounter> counter = Ray.actor(InitCounter::new, 10).remote();

Related Pages

Implements Principle

• Principle:Ray_project_Ray_Actor_Class_Definition

Requires Environment

• Environment:Ray_project_Ray_Java_Build_Environment