0
# Ray Runtime Java
1

2
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).
3

4
## Package Information
5

6
- **Package Name**: ray-runtime
7
- **Package Type**: Maven
8
- **Group ID**: io.ray
9
- **Artifact ID**: ray-runtime
10
- **Language**: Java
11
- **Installation**: `io.ray:ray-runtime:2.47.1`
12

13
## Core Imports
14

15
```java
16
import io.ray.api.Ray;
17
import io.ray.api.ObjectRef;
18
import io.ray.api.ActorHandle;
19
import io.ray.api.WaitResult;
20
```
21

22
## Basic Usage
23

24
```java
25
import io.ray.api.Ray;
26
import io.ray.api.ObjectRef;
27

28
// Initialize Ray runtime
29
Ray.init();
30

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

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

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

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

47
// Shutdown
48
Ray.shutdown();
49
```
50

51
## Architecture
52

53
Ray Java runtime is built around several key architectural components:
54

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

62
## Capabilities
63

64
### Core Runtime & Lifecycle
65

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

68
```java { .api }
69
// Main entry point
70
public static void init();
71
public static void shutdown();
72
public static boolean isInitialized();
73
public static RuntimeContext getRuntimeContext();
74
```
75

76
[Runtime Management](./runtime.md)
77

78
### Object Store Operations
79

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

82
```java { .api }
83
public static <T> ObjectRef<T> put(T obj);
84
public static <T> ObjectRef<T> put(T obj, BaseActorHandle owner);
85
public static <T> T get(ObjectRef<T> objectRef);
86
public static <T> T get(ObjectRef<T> objectRef, long timeoutMs);
87
public static <T> List<T> get(List<ObjectRef<T>> objectList);
88
public static <T> WaitResult<T> wait(List<ObjectRef<T>> waitList, int numReturns, int timeoutMs);
89
public static <T> WaitResult<T> wait(List<ObjectRef<T>> waitList, int numReturns, int timeoutMs, boolean fetchLocal);
90
```
91

92
[Object Store](./object-store.md)
93

94
### Remote Task Execution
95

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

98
```java { .api }
99
// Task creation methods (0-6 parameters)
100
public static <R> TaskCaller<R> task(RayFunc0<R> f);
101
public static <T0, R> TaskCaller<R> task(RayFunc1<T0, R> f, T0 t0);
102
public static <T0> VoidTaskCaller task(RayFuncVoid1<T0> f, T0 t0);
103
// ... up to 6 parameters
104

105
// Task execution
106
public interface TaskCaller<R> {
107
    ObjectRef<R> remote();
108
}
109
```
110

111
[Task Execution](./tasks.md)
112

113
### Actor Model Programming
114

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

117
```java { .api }
118
// Actor creation methods (0-6 parameters)
119
public static <A> ActorCreator<A> actor(RayFunc0<A> f);
120
public static <T0, A> ActorCreator<A> actor(RayFunc1<T0, A> f, T0 t0);
121
// ... up to 6 parameters
122

123
// Actor creation options
124
public class ActorCreationOptions {
125
    public static final int NO_RESTART = 0;
126
    public static final int INFINITE_RESTART = -1;
127
    
128
    public static Builder builder();
129
    
130
    public static class Builder {
131
        public Builder setName(String name);
132
        public Builder setLifetime(ActorLifetime lifetime);
133
        public Builder setResources(Map<String, Double> resources);
134
        public Builder setMaxRestarts(int maxRestarts);
135
        public Builder setJvmOptions(List<String> jvmOptions);
136
        public Builder setMaxConcurrency(int maxConcurrency);
137
        public ActorCreationOptions build();
138
    }
139
}
140

141
public enum ActorLifetime {
142
    DETACHED, NON_DETACHED
143
}
144

145
// Actor configuration
146
public interface ActorCreator<A> {
147
    ActorHandle<A> remote();
148
    ActorCreator<A> setJvmOptions(List<String> jvmOptions);
149
    ActorCreator<A> setMaxConcurrency(int maxConcurrency);
150
    ActorCreator<A> setRuntimeEnv(RuntimeEnv runtimeEnv);
151
}
152

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

158
// Actor interfaces
159
public interface BaseActorHandle {
160
    ActorId getId();
161
    void kill();
162
    void kill(boolean noRestart);
163
}
164
```
165

166
[Actor Programming](./actors.md)
167

168
### Cross-Language Integration
169

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

172
```java { .api }
173
// Python integration
174
public static <R> PyTaskCaller<R> task(PyFunction<R> pyFunction);
175
public static PyActorCreator actor(PyActorClass pyActorClass);
176

177
// C++ integration  
178
public static <R> CppTaskCaller<R> task(CppFunction<R> cppFunction);
179
public static CppActorCreator actor(CppActorClass cppActorClass);
180
```
181

182
[Cross-Language Features](./cross-language.md)
183

184
### Placement Groups
185

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

188
```java { .api }
189
public class PlacementGroups {
190
    public static PlacementGroup createPlacementGroup(PlacementGroupCreationOptions options);
191
    public static PlacementGroup getPlacementGroup(PlacementGroupId id);
192
    public static List<PlacementGroup> getAllPlacementGroups();
193
    public static void removePlacementGroup(PlacementGroupId id);
194
}
195

196
public interface PlacementGroup {
197
    PlacementGroupId getId();
198
    String getName();
199
    boolean wait(int timeoutSeconds);
200
}
201

202
// Placement strategies
203
public enum PlacementStrategy {
204
    PACK,        // Pack bundles close together
205
    SPREAD,      // Distribute bundles across nodes
206
    STRICT_PACK, // Pack into one node only
207
    STRICT_SPREAD // One bundle per node
208
}
209

210
// Placement group states
211
public enum PlacementGroupState {
212
    PENDING,      // Waiting for resources
213
    CREATED,      // Successfully created
214
    REMOVED,      // Placement group removed
215
    RESCHEDULING  // Currently rescheduling
216
}
217
```
218

219
[Placement Groups](./placement-groups.md)
220

221
### Advanced Actor Features
222

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

225
```java { .api }
226
// Parallel actors
227
public class ParallelActor {
228
    // Base class for parallel actor implementations
229
}
230

231
public interface ParallelActorHandle {
232
    // Handle for parallel actor instances
233
}
234

235
// Concurrency groups
236
public interface ConcurrencyGroup {
237
    // Concurrency group interface
238
}
239
```
240

241
[Advanced Actor Features](./advanced-actors.md)
242

243
## Exception Handling
244

245
```java { .api }
246
// Base exception hierarchy
247
public class RayException extends RuntimeException {}
248

249
// Core operation exceptions
250
public class RayTimeoutException extends RayException {}
251
public class RayTaskException extends RayException {}
252
public class RayActorException extends RayException {}
253

254
// Advanced operation exceptions
255
public class CrossLanguageException extends RayException {}
256
public class UnreconstructableException extends RayException {}
257
public class RuntimeEnvException extends RayException {}
258
public class RayWorkerException extends RayException {}
259
public class RayIntentionalSystemExitException extends RayException {}
260
public class PendingCallsLimitExceededException extends RayException {}
261
```
262

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

265
## Types
266

267
### Core Reference Types
268

269
```java { .api }
270
public interface ObjectRef<T> {
271
    T get();
272
    T get(long timeoutMs);
273
}
274

275
public class WaitResult<T> {
276
    public List<ObjectRef<T>> getReady();
277
    public List<ObjectRef<T>> getUnready();
278
}
279
```
280

281
### ID System
282

283
```java { .api }
284
public abstract class BaseId {
285
    public byte[] getBytes();
286
    public boolean isNil();
287
    public int size();
288
}
289

290
public class ActorId extends BaseId {}
291
public class TaskId extends BaseId {}
292
public class ObjectId extends BaseId {}
293
public class JobId extends BaseId {}
294
public class PlacementGroupId extends BaseId {}
295
```
296

297
### Function Interfaces
298

299
```java { .api }
300
// Return value functions (0-6 parameters)
301
public interface RayFunc0<R> { R apply(); }
302
public interface RayFunc1<T0, R> { R apply(T0 t0); }
303
public interface RayFunc2<T0, T1, R> { R apply(T0 t0, T1 t1); }
304
// ... up to RayFunc6
305

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