Implementation:Ray project Ray RayRuntime Interface

Knowledge Sources	Ray
Domains	Distributed_Computing, Java_API
Last Updated	2026-02-13 16:00 GMT

Overview

Central runtime interface that exposes all core Ray operations to Java applications provided by the Ray Java API.

Description

RayRuntime is the foundational API contract of the Ray Java SDK, declaring a comprehensive interface with methods organized into several categories: object store operations (put, get, wait, free), remote task invocation (call for Java, Python, and C++ functions), actor lifecycle management (createActor, getActor, killActor, exitActor), placement group management (createPlacementGroup, getPlacementGroup, removePlacementGroup), and runtime introspection (getRuntimeContext, getAvailableResourceIds, getNamespace). It supports cross-language actors via typed handles (ActorHandle, PyActorHandle, CppActorHandle).

Usage

Use this interface as the single point of abstraction that decouples user-facing Ray API calls from the underlying execution engine. Every runtime implementation (native runtime, test runtime, etc.) must implement this interface.

Code Reference

Source Location

• Repository: Ray
• File: java/api/src/main/java/io/ray/api/runtime/RayRuntime.java

Signature

public interface RayRuntime {
    void shutdown();
    <T> ObjectRef<T> put(T obj);
    <T> ObjectRef<T> put(T obj, BaseActorHandle owner);
    <T> T get(ObjectRef<T> objectRef);
    <T> List<T> get(List<ObjectRef<T>> objectRefs);
    <T> T get(ObjectRef<T> objectRef, long timeoutMs);
    <T> List<T> get(List<ObjectRef<T>> objectRefs, long timeoutMs);
    <T> WaitResult<T> wait(List<ObjectRef<T>> waitList, int numReturns, int timeoutMs, boolean fetchLocal);
    void free(List<ObjectRef<?>> objectRefs, boolean localOnly);
    <T extends BaseActorHandle> T getActorHandle(ActorId actorId);
    <T extends BaseActorHandle> Optional<T> getActor(String name, String namespace);
    void killActor(BaseActorHandle actor, boolean noRestart);
    ObjectRef call(RayFunc func, Object[] args, CallOptions options);
    ObjectRef call(PyFunction pyFunction, Object[] args, CallOptions options);
    ObjectRef call(CppFunction cppFunction, Object[] args, CallOptions options);
    ObjectRef callActor(ActorHandle<?> actor, RayFunc func, Object[] args, CallOptions options);
    ObjectRef callActor(PyActorHandle pyActor, PyActorMethod pyActorMethod, Object[] args);
    ObjectRef callActor(CppActorHandle cppActor, CppActorMethod cppActorMethod, Object[] args);
    <T> ActorHandle<T> createActor(RayFunc actorFactoryFunc, Object[] args, ActorCreationOptions options);
    PyActorHandle createActor(PyActorClass pyActorClass, Object[] args, ActorCreationOptions options);
    CppActorHandle createActor(CppActorClass cppActorClass, Object[] args, ActorCreationOptions options);
    PlacementGroup createPlacementGroup(PlacementGroupCreationOptions creationOptions);
    RuntimeContext getRuntimeContext();
    void exitActor();
    Map<String, List<ResourceValue>> getAvailableResourceIds();
    String getNamespace();
    UniqueId getCurrentNodeId();
    PlacementGroup getPlacementGroup(PlacementGroupId id);
    PlacementGroup getPlacementGroup(String name, String namespace);
    List<PlacementGroup> getAllPlacementGroups();
    void removePlacementGroup(PlacementGroupId id);
    boolean waitPlacementGroupReady(PlacementGroupId id, int timeoutSeconds);
    ConcurrencyGroup createConcurrencyGroup(String name, int maxConcurrency, List<RayFunc> funcs);
    List<ConcurrencyGroup> extractConcurrencyGroups(RayFuncR<?> actorConstructorLambda);
    RuntimeEnv createRuntimeEnv();
    RuntimeEnv deserializeRuntimeEnv(String serializedRuntimeEnv) throws RuntimeEnvException;
    ParallelActorContext getParallelActorContext();
}

Import

import io.ray.api.runtime.RayRuntime;

I/O Contract

Inputs

Name	Type	Required	Description
obj	T	Yes	Java object to store in the object store (for put)
objectRef	ObjectRef<T>	Yes	Reference to an object in the object store (for get)
func	RayFunc	Yes	Remote function reference (for call)
actor	ActorHandle<?>	Yes	Handle to a remote actor (for callActor)
options	CallOptions / ActorCreationOptions	No	Options for configuring task or actor creation
creationOptions	PlacementGroupCreationOptions	Yes	Options for creating a placement group

Outputs

Name	Type	Description
objectRef	ObjectRef<T>	Reference to an object stored in the object store
result	T	Retrieved Java object from the object store
actorHandle	ActorHandle<T>	Handle to a created or retrieved actor
placementGroup	PlacementGroup	Handle to a created or retrieved placement group
waitResult	WaitResult<T>	Two lists of ready and unready objects

Usage Examples

// Accessed via Ray.internal() which returns the RayRuntime instance
RayRuntime runtime = Ray.internal();

// Store and retrieve an object
ObjectRef<String> ref = runtime.put("hello");
String value = runtime.get(ref);

// Invoke a remote function
ObjectRef result = runtime.call(myFunc, new Object[]{arg1}, callOptions);

// Create an actor
ActorHandle<MyActor> actor = runtime.createActor(MyActor::new, new Object[]{}, options);

// Create a placement group
PlacementGroup pg = runtime.createPlacementGroup(pgOptions);

Related Pages

• Environment:Ray_project_Ray_Java_Build_Environment