Implementation:Ray project Ray ActorHandle Kill

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

Overview

Concrete tool for terminating remote actor processes provided by the Ray Java SDK.

Description

Two APIs are available for actor termination:

• handle.kill() — External termination. Sends a kill signal to the actor via RayNativeRuntime.killActor() (JNI to nativeKillActor()). By default, noRestart=true prevents automatic restart.
• Ray.exitActor() — Self-termination from within an actor method. Throws RayIntentionalSystemExitException to cleanly exit the actor worker process. Only callable from within an actor context.

Usage

Use handle.kill() to terminate an actor from the outside. Use Ray.exitActor() within an actor method for self-initiated termination.

Code Reference

Source Location

• Repository: ray-project/ray
• File: java/api/src/main/java/io/ray/api/ActorHandle.java (L1-28, interface)
• File: java/runtime/src/main/java/io/ray/runtime/RayNativeRuntime.java (L196-198 killActor, L207-214 exitActor)
• File: java/api/src/main/java/io/ray/api/Ray.java (L228-230, exitActor)

Signature

// External kill (on BaseActorHandle, inherited by ActorHandle)
void kill()
void kill(boolean noRestart)

// Self-exit (static method on Ray)
public static void exitActor()

Import

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

I/O Contract

Inputs

Name	Type	Required	Description
noRestart	boolean	No	If true, the killed actor will not be restarted (default: true)

Outputs

Name	Type	Description
(side effect)	void	Actor process is terminated. Subsequent calls throw RayActorException.

Usage Examples

External Kill

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

public class KillExample {
    public static class Worker {
        public String work() { return "done"; }
    }

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

        ActorHandle<Worker> worker = Ray.actor(Worker::new).remote();
        worker.task(Worker::work).remote().get();

        // Kill the actor (no restart)
        worker.kill();

        Ray.shutdown();
    }
}

Self-Exit from Within Actor

public static class SelfTerminatingWorker {
    private int callCount = 0;

    public String doWork() {
        callCount++;
        if (callCount >= 10) {
            // Gracefully exit after 10 calls
            Ray.exitActor();
        }
        return "call #" + callCount;
    }
}

Related Pages

Implements Principle

• Principle:Ray_project_Ray_Actor_Termination

Requires Environment

• Environment:Ray_project_Ray_Java_Build_Environment