or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

actors.mdadvanced-actors.mdcross-language.mdindex.mdobject-store.mdplacement-groups.mdruntime.mdtasks.md
tile.json

tessl/maven-io-ray--ray-runtime

Ray runtime implementation for Java - the core distributed runtime component of Ray framework for scaling AI and Python applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.ray/ray-runtime@2.47.x

To install, run

npx @tessl/cli install tessl/maven-io-ray--ray-runtime@2.47.0

index.mddocs/

Ray Runtime Java

Ray runtime implementation for Java provides the core distributed computing runtime that enables Java applications to leverage Ray's distributed system capabilities. This library implements the fundamental abstractions for distributed execution including tasks (stateless functions), actors (stateful worker processes), and objects (immutable values accessible across the cluster).

Package Information

  • Package Name: ray-runtime
  • Package Type: Maven
  • Group ID: io.ray
  • Artifact ID: ray-runtime
  • Language: Java
  • Installation: io.ray:ray-runtime:2.47.1

Core Imports

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

Basic Usage

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

// Initialize Ray runtime
Ray.init();

// Store objects in distributed object store
ObjectRef<String> objRef = Ray.put("Hello Ray!");
String value = Ray.get(objRef);

// Create and call remote tasks
ObjectRef<Integer> result = Ray.task(MyClass::myMethod, 42).remote();
Integer finalResult = Ray.get(result);

// Create actors (stateful distributed workers)
ActorHandle<MyActor> actor = Ray.actor(MyActor::new, "actor-param").remote();
ObjectRef<String> actorResult = actor.task(MyActor::processData, "data").remote();

// Wait for multiple objects
List<ObjectRef<String>> refs = Arrays.asList(ref1, ref2, ref3);
WaitResult<String> waitResult = Ray.wait(refs, 2, 5000); // Wait for 2 objects, 5s timeout

// Shutdown
Ray.shutdown();

Architecture

Ray Java runtime is built around several key architectural components:

  • Single Entry Point: Ray class provides all distributed computing operations via static methods
  • Object Store: Distributed shared memory system with ObjectRef<T> handles for zero-copy data sharing
  • Task System: Type-safe remote function execution with 0-6 parameter support and ObjectRef chaining
  • Actor Model: Stateful distributed workers with method-level task execution and lifecycle management
  • Cross-Language Integration: Full Python and C++ interoperability for polyglot distributed computing
  • Advanced Patterns: Placement groups, parallel actors, and concurrency groups for sophisticated workload management

Capabilities

Core Runtime & Lifecycle

Essential runtime management including initialization, shutdown, and context access.

// Main entry point
public static void init();
public static void shutdown();
public static boolean isInitialized();
public static RuntimeContext getRuntimeContext();

Runtime Management

Object Store Operations

Distributed object storage with type-safe references for zero-copy data sharing across cluster nodes.

public static <T> ObjectRef<T> put(T obj);
public static <T> ObjectRef<T> put(T obj, BaseActorHandle owner);
public static <T> T get(ObjectRef<T> objectRef);
public static <T> T get(ObjectRef<T> objectRef, long timeoutMs);
public static <T> List<T> get(List<ObjectRef<T>> objectList);
public static <T> WaitResult<T> wait(List<ObjectRef<T>> waitList, int numReturns, int timeoutMs);
public static <T> WaitResult<T> wait(List<ObjectRef<T>> waitList, int numReturns, int timeoutMs, boolean fetchLocal);

Object Store

Remote Task Execution

Type-safe distributed function execution with support for 0-6 parameters and ObjectRef chaining.

// Task creation methods (0-6 parameters)
public static <R> TaskCaller<R> task(RayFunc0<R> f);
public static <T0, R> TaskCaller<R> task(RayFunc1<T0, R> f, T0 t0);
public static <T0> VoidTaskCaller task(RayFuncVoid1<T0> f, T0 t0);
// ... up to 6 parameters

// Task execution
public interface TaskCaller<R> {
    ObjectRef<R> remote();
}

Task Execution

Actor Model Programming

Stateful distributed workers with method-level task execution, lifecycle management, and resource control.

// Actor creation methods (0-6 parameters)
public static <A> ActorCreator<A> actor(RayFunc0<A> f);
public static <T0, A> ActorCreator<A> actor(RayFunc1<T0, A> f, T0 t0);
// ... up to 6 parameters

// Actor creation options
public class ActorCreationOptions {
    public static final int NO_RESTART = 0;
    public static final int INFINITE_RESTART = -1;
    
    public static Builder builder();
    
    public static class Builder {
        public Builder setName(String name);
        public Builder setLifetime(ActorLifetime lifetime);
        public Builder setResources(Map<String, Double> resources);
        public Builder setMaxRestarts(int maxRestarts);
        public Builder setJvmOptions(List<String> jvmOptions);
        public Builder setMaxConcurrency(int maxConcurrency);
        public ActorCreationOptions build();
    }
}

public enum ActorLifetime {
    DETACHED, NON_DETACHED
}

// Actor configuration
public interface ActorCreator<A> {
    ActorHandle<A> remote();
    ActorCreator<A> setJvmOptions(List<String> jvmOptions);
    ActorCreator<A> setMaxConcurrency(int maxConcurrency);
    ActorCreator<A> setRuntimeEnv(RuntimeEnv runtimeEnv);
}

// Actor management
public static <T extends BaseActorHandle> Optional<T> getActor(String name);
public static <T extends BaseActorHandle> Optional<T> getActor(String name, String namespace);
public static void exitActor();

// Actor interfaces
public interface BaseActorHandle {
    ActorId getId();
    void kill();
    void kill(boolean noRestart);
}

Actor Programming

Cross-Language Integration

Complete Python and C++ integration enabling polyglot distributed computing workflows.

// Python integration
public static <R> PyTaskCaller<R> task(PyFunction<R> pyFunction);
public static PyActorCreator actor(PyActorClass pyActorClass);

// C++ integration  
public static <R> CppTaskCaller<R> task(CppFunction<R> cppFunction);
public static CppActorCreator actor(CppActorClass cppActorClass);

Cross-Language Features

Placement Groups

Resource management and co-location control for distributed workloads with bundle-based scheduling.

public class PlacementGroups {
    public static PlacementGroup createPlacementGroup(PlacementGroupCreationOptions options);
    public static PlacementGroup getPlacementGroup(PlacementGroupId id);
    public static List<PlacementGroup> getAllPlacementGroups();
    public static void removePlacementGroup(PlacementGroupId id);
}

public interface PlacementGroup {
    PlacementGroupId getId();
    String getName();
    boolean wait(int timeoutSeconds);
}

// Placement strategies
public enum PlacementStrategy {
    PACK,        // Pack bundles close together
    SPREAD,      // Distribute bundles across nodes
    STRICT_PACK, // Pack into one node only
    STRICT_SPREAD // One bundle per node
}

// Placement group states
public enum PlacementGroupState {
    PENDING,      // Waiting for resources
    CREATED,      // Successfully created
    REMOVED,      // Placement group removed
    RESCHEDULING  // Currently rescheduling
}

Placement Groups

Advanced Actor Features

Specialized actor patterns including parallel actors and concurrency group management for high-performance scenarios.

// Parallel actors
public class ParallelActor {
    // Base class for parallel actor implementations
}

public interface ParallelActorHandle {
    // Handle for parallel actor instances
}

// Concurrency groups
public interface ConcurrencyGroup {
    // Concurrency group interface
}

Advanced Actor Features

Exception Handling

// Base exception hierarchy
public class RayException extends RuntimeException {}

// Core operation exceptions
public class RayTimeoutException extends RayException {}
public class RayTaskException extends RayException {}
public class RayActorException extends RayException {}

// Advanced operation exceptions
public class CrossLanguageException extends RayException {}
public class UnreconstructableException extends RayException {}
public class RuntimeEnvException extends RayException {}
public class RayWorkerException extends RayException {}
public class RayIntentionalSystemExitException extends RayException {}
public class PendingCallsLimitExceededException extends RayException {}

Ray provides comprehensive exception handling with specific exception types for different failure scenarios including timeouts, task failures, actor errors, and cross-language integration issues.

Types

Core Reference Types

public interface ObjectRef<T> {
    T get();
    T get(long timeoutMs);
}

public class WaitResult<T> {
    public List<ObjectRef<T>> getReady();
    public List<ObjectRef<T>> getUnready();
}

ID System

public abstract class BaseId {
    public byte[] getBytes();
    public boolean isNil();
    public int size();
}

public class ActorId extends BaseId {}
public class TaskId extends BaseId {}
public class ObjectId extends BaseId {}
public class JobId extends BaseId {}
public class PlacementGroupId extends BaseId {}

Function Interfaces

// Return value functions (0-6 parameters)
public interface RayFunc0<R> { R apply(); }
public interface RayFunc1<T0, R> { R apply(T0 t0); }
public interface RayFunc2<T0, T1, R> { R apply(T0 t0, T1 t1); }
// ... up to RayFunc6

// Void functions (0-6 parameters)  
public interface RayFuncVoid0 { void apply(); }
public interface RayFuncVoid1<T0> { void apply(T0 t0); }
// ... up to RayFuncVoid6