Implementation:Ray project Ray ActorHandle Task Remote

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

Overview

Concrete tool for invoking methods on remote actors through actor handles provided by the Ray Java SDK.

Description

The ActorHandle.task() method creates an ActorTaskCaller builder, and calling .remote() dispatches the method call to the remote actor. The ActorCall interface (implemented by ActorHandle) provides type-safe overloads for methods with 0 to 6 parameters (plus the implicit actor self parameter). ActorTaskCaller.remote() delegates to Ray.internal().callActor(actor, func, args, options).

Usage

Use handle.task(Method).remote() to invoke any public method on a remote actor. The method reference's first type parameter must match the actor class type.

Code Reference

Source Location

• Repository: ray-project/ray
• File: java/api/src/main/java/io/ray/api/ActorCall.java (L1-655, type-safe overloads)
• File: java/api/src/main/java/io/ray/api/call/ActorTaskCaller.java (L1-45)

Signature

// On ActorCall<A> (implemented by ActorHandle<A>)
// 0-argument method
<R> ActorTaskCaller<R> task(RayFunc1<A, R> f)
// 1-argument method
<R, T0> ActorTaskCaller<R> task(RayFunc2<A, T0, R> f, T0 t0)
// ... up to 5 additional method parameters

// Submit the actor method call
public ObjectRef<R> remote()

Import

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

I/O Contract

Inputs

Name	Type	Required	Description
f	RayFuncN<A, ..., R>	Yes	Actor method reference (first type param is the actor class)
args	T0, T1, ...	Depends on arity	Method arguments
concurrencyGroup	String	No	Name of the concurrency group for this call

Outputs

Name	Type	Description
result	ObjectRef<R>	Future reference to the method's return value

Usage Examples

Invoke Actor Methods

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

public class ActorInvocation {
    public static class Counter {
        private int value = 0;

        public int increment() { return ++value; }
        public int add(int delta) { value += delta; return value; }
        public int getValue() { return value; }
    }

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

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

        // 0-arg method invocation
        ObjectRef<Integer> r1 = counter.task(Counter::increment).remote();

        // 1-arg method invocation
        ObjectRef<Integer> r2 = counter.task(Counter::add, 5).remote();

        // Get results
        System.out.println(r1.get()); // 1
        System.out.println(r2.get()); // 6

        Ray.shutdown();
    }
}

Related Pages

Implements Principle

• Principle:Ray_project_Ray_Actor_Method_Invocation

Requires Environment

• Environment:Ray_project_Ray_Java_Build_Environment