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
```