0
# Object Store
1

2
Distributed object storage system providing type-safe references for zero-copy data sharing across cluster nodes.
3

4
## Capabilities
5

6
### Object Storage
7

8
Store objects in the distributed object store and get references for sharing across tasks and actors.
9

10
```java { .api }
11
/**
12
 * Store an object in the object store.
13
 * @param obj The Java object to be stored
14
 * @return ObjectRef instance representing the stored object
15
 */
16
public static <T> ObjectRef<T> put(T obj);
17

18
/**
19
 * Store an object with specified ownership.
20
 * @param obj The Java object to be stored
21
 * @param owner The actor that should own this object
22
 * @return ObjectRef instance representing the stored object
23
 */
24
public static <T> ObjectRef<T> put(T obj, BaseActorHandle owner);
25
```
26

27
**Usage Examples:**
28

29
```java
30
import io.ray.api.Ray;
31
import io.ray.api.ObjectRef;
32

33
// Store simple objects
34
ObjectRef<String> stringRef = Ray.put("Hello Ray!");
35
ObjectRef<Integer> numberRef = Ray.put(42);
36

37
// Store complex objects
38
List<String> data = Arrays.asList("item1", "item2", "item3");
39
ObjectRef<List<String>> listRef = Ray.put(data);
40

41
// Store with actor ownership
42
ActorHandle<MyActor> actor = Ray.actor(MyActor::new).remote();
43
ObjectRef<String> ownedRef = Ray.put("owned-data", actor);
44
```
45

46
### Object Retrieval
47

48
Retrieve objects from the object store using their references.
49

50
```java { .api }
51
/**
52
 * Get an object by ObjectRef from the object store.
53
 * Blocks until the object is available.
54
 * @param objectRef The reference of the object to get
55
 * @return The Java object
56
 */
57
public static <T> T get(ObjectRef<T> objectRef);
58

59
/**
60
 * Get an object with timeout.
61
 * @param objectRef The reference of the object to get
62
 * @param timeoutMs Maximum time to wait in milliseconds
63
 * @return The Java object
64
 * @throws RayTimeoutException if timeout is exceeded
65
 */
66
public static <T> T get(ObjectRef<T> objectRef, long timeoutMs);
67

68
/**
69
 * Get multiple objects.
70
 * @param objectList List of object references
71
 * @return List of Java objects in the same order
72
 */
73
public static <T> List<T> get(List<ObjectRef<T>> objectList);
74

75
/**
76
 * Get multiple objects with timeout.
77
 * @param objectList List of object references
78
 * @param timeoutMs Maximum time to wait in milliseconds
79
 * @return List of Java objects in the same order
80
 * @throws RayTimeoutException if timeout is exceeded
81
 */
82
public static <T> List<T> get(List<ObjectRef<T>> objectList, long timeoutMs);
83
```
84

85
**Usage Examples:**
86

87
```java
88
// Single object retrieval
89
ObjectRef<String> ref = Ray.put("Hello");
90
String value = Ray.get(ref);
91
System.out.println(value); // "Hello"
92

93
// Retrieval with timeout
94
try {
95
    String result = Ray.get(ref, 5000); // Wait max 5 seconds
96
} catch (RayTimeoutException e) {
97
    System.out.println("Object not ready within timeout");
98
}
99

100
// Multiple object retrieval
101
List<ObjectRef<Integer>> refs = Arrays.asList(
102
    Ray.put(1), Ray.put(2), Ray.put(3)
103
);
104
List<Integer> values = Ray.get(refs);
105
System.out.println(values); // [1, 2, 3]
106
```
107

108
### Wait Operations
109

110
Wait for objects to become available without retrieving their values.
111

112
```java { .api }
113
/**
114
 * Wait for objects to be available.
115
 * @param waitList List of object references to wait for
116
 * @param numReturns Number of objects that should be ready
117
 * @param timeoutMs Maximum time to wait in milliseconds
118
 * @param fetchLocal If true, fetch objects locally before returning
119
 * @return WaitResult containing ready and unready object lists
120
 */
121
public static <T> WaitResult<T> wait(
122
    List<ObjectRef<T>> waitList, 
123
    int numReturns, 
124
    int timeoutMs, 
125
    boolean fetchLocal
126
);
127

128
/**
129
 * Wait for objects locally (fetchLocal = true).
130
 * @param waitList List of object references to wait for
131
 * @param numReturns Number of objects that should be ready
132
 * @param timeoutMs Maximum time to wait in milliseconds
133
 * @return WaitResult containing ready and unready object lists
134
 */
135
public static <T> WaitResult<T> wait(
136
    List<ObjectRef<T>> waitList, 
137
    int numReturns, 
138
    int timeoutMs
139
);
140

141
/**
142
 * Wait for objects with no timeout.
143
 * @param waitList List of object references to wait for
144
 * @param numReturns Number of objects that should be ready
145
 * @return WaitResult containing ready and unready object lists
146
 */
147
public static <T> WaitResult<T> wait(
148
    List<ObjectRef<T>> waitList, 
149
    int numReturns
150
);
151

152
/**
153
 * Wait for all objects.
154
 * @param waitList List of object references to wait for
155
 * @return WaitResult containing ready and unready object lists
156
 */
157
public static <T> WaitResult<T> wait(List<ObjectRef<T>> waitList);
158
```
159

160
**Usage Examples:**
161

162
```java
163
// Start multiple long-running tasks
164
List<ObjectRef<String>> taskRefs = Arrays.asList(
165
    Ray.task(MyClass::longTask, "task1").remote(),
166
    Ray.task(MyClass::longTask, "task2").remote(),
167
    Ray.task(MyClass::longTask, "task3").remote()
168
);
169

170
// Wait for any 2 tasks to complete within 10 seconds
171
WaitResult<String> result = Ray.wait(taskRefs, 2, 10000);
172

173
System.out.println("Ready tasks: " + result.getReady().size());
174
System.out.println("Unready tasks: " + result.getUnready().size());
175

176
// Process completed tasks
177
for (ObjectRef<String> readyRef : result.getReady()) {
178
    String taskResult = Ray.get(readyRef);
179
    System.out.println("Task completed: " + taskResult);
180
}
181

182
// Wait for all remaining tasks
183
if (!result.getUnready().isEmpty()) {
184
    WaitResult<String> remaining = Ray.wait(result.getUnready());
185
    // Process remaining results...
186
}
187
```
188

189
### Object Reference Interface
190

191
Direct interface for working with object references.
192

193
```java { .api }
194
public interface ObjectRef<T> {
195
    /**
196
     * Get the object (blocking).
197
     * @return The object value
198
     */
199
    T get();
200
    
201
    /**
202
     * Get the object with timeout.
203
     * @param timeoutMs Maximum time to wait in milliseconds
204
     * @return The object value
205
     * @throws RayTimeoutException if timeout is exceeded
206
     */
207
    T get(long timeoutMs);
208
}
209
```
210

211
**Usage Example:**
212

213
```java
214
ObjectRef<String> ref = Ray.put("data");
215

216
// Using ObjectRef interface directly
217
String value1 = ref.get();
218
String value2 = ref.get(5000);
219

220
// ObjectRefs can be passed around
221
public void processRef(ObjectRef<String> ref) {
222
    String data = ref.get();
223
    // Process data...
224
}
225
```
226

227
## Supporting Types
228

229
### Wait Result
230

231
```java { .api }
232
public class WaitResult<T> {
233
    /**
234
     * Get list of object references that are ready.
235
     * @return List of ready ObjectRef instances
236
     */
237
    public List<ObjectRef<T>> getReady();
238
    
239
    /**
240
     * Get list of object references that are not ready.
241
     * @return List of unready ObjectRef instances
242
     */
243
    public List<ObjectRef<T>> getUnready();
244
}
245
```
246

247
## Best Practices
248

249
### Memory Management
250

251
```java
252
// Store large objects to avoid copying
253
List<LargeObject> bigData = createLargeDataset();
254
ObjectRef<List<LargeObject>> dataRef = Ray.put(bigData);
255

256
// Pass reference instead of data
257
ObjectRef<ProcessedData> result = Ray.task(MyProcessor::process, dataRef).remote();
258
```
259

260
### Error Handling
261

262
```java
263
try {
264
    ObjectRef<String> ref = Ray.put("data");
265
    String value = Ray.get(ref, 5000);
266
} catch (RayTimeoutException e) {
267
    System.out.println("Object not ready: " + e.getMessage());
268
} catch (RayException e) {
269
    System.out.println("Ray error: " + e.getMessage());
270
}
271
```
272

273
### Ownership Management
274

275
```java
276
// Create actor
277
ActorHandle<DataProcessor> processor = Ray.actor(DataProcessor::new).remote();
278

279
// Store data with actor ownership
280
ObjectRef<String> data = Ray.put("important-data", processor);
281

282
// Data will be cleaned up when actor dies
283
processor.task(DataProcessor::shutdown).remote();
284
```