0
# Placement Groups
1

2
Resource management and co-location control for distributed workloads with bundle-based scheduling and sophisticated placement strategies.
3

4
## Capabilities
5

6
### Placement Group Management
7

8
Create and manage placement groups for controlling resource allocation and task co-location.
9

10
```java { .api }
11
public class PlacementGroups {
12
    /**
13
     * Create a new placement group.
14
     * @param options Configuration for the placement group
15
     * @return PlacementGroup instance
16
     */
17
    public static PlacementGroup createPlacementGroup(PlacementGroupCreationOptions options);
18
    
19
    /**
20
     * Get placement group by ID.
21
     * @param id Placement group ID
22
     * @return PlacementGroup instance or null if not found
23
     */
24
    public static PlacementGroup getPlacementGroup(PlacementGroupId id);
25
    
26
    /**
27
     * Get placement group by name.
28
     * @param name Placement group name
29
     * @return PlacementGroup instance or null if not found
30
     */
31
    public static PlacementGroup getPlacementGroup(String name);
32
    
33
    /**
34
     * Get placement group by name and namespace.
35
     * @param name Placement group name
36
     * @param namespace Namespace to search in
37
     * @return PlacementGroup instance or null if not found
38
     */
39
    public static PlacementGroup getPlacementGroup(String name, String namespace);
40
    
41
    /**
42
     * Get all placement groups in the cluster.
43
     * @return List of all placement groups
44
     */
45
    public static List<PlacementGroup> getAllPlacementGroups();
46
    
47
    /**
48
     * Remove a placement group.
49
     * @param id Placement group ID to remove
50
     */
51
    public static void removePlacementGroup(PlacementGroupId id);
52
}
53
```
54

55
**Usage Examples:**
56

57
```java
58
import io.ray.api.Ray;
59
import io.ray.api.PlacementGroups;
60
import io.ray.api.placementgroup.PlacementGroup;
61
import io.ray.api.placementgroup.PlacementStrategy;
62
import io.ray.api.options.PlacementGroupCreationOptions;
63

64
public class PlacementGroupExample {
65
    public static void main(String[] args) {
66
        Ray.init();
67
        
68
        // Define resource bundles
69
        List<Map<String, Double>> bundles = Arrays.asList(
70
            Map.of("CPU", 2.0, "GPU", 1.0),  // Bundle 1: 2 CPUs, 1 GPU
71
            Map.of("CPU", 2.0),              // Bundle 2: 2 CPUs
72
            Map.of("CPU", 1.0)               // Bundle 3: 1 CPU
73
        );
74
        
75
        // Create placement group options
76
        PlacementGroupCreationOptions options = PlacementGroupCreationOptions.builder()
77
            .setName("ml-training-group")
78
            .setBundles(bundles)
79
            .setStrategy(PlacementStrategy.STRICT_PACK)
80
            .build();
81
        
82
        // Create placement group
83
        PlacementGroup pg = PlacementGroups.createPlacementGroup(options);
84
        
85
        // Wait for placement group to be ready
86
        boolean ready = pg.wait(30); // Wait up to 30 seconds
87
        if (ready) {
88
            System.out.println("Placement group ready: " + pg.getId());
89
        } else {
90
            System.out.println("Placement group creation timed out");
91
        }
92
        
93
        // Use placement group for tasks and actors...
94
        
95
        // Clean up
96
        PlacementGroups.removePlacementGroup(pg.getId());
97
        
98
        Ray.shutdown();
99
    }
100
}
101
```
102

103
### Placement Group Interface
104

105
Core placement group operations and information access.
106

107
```java { .api }
108
public interface PlacementGroup {
109
    /**
110
     * Get the placement group ID.
111
     * @return PlacementGroupId
112
     */
113
    PlacementGroupId getId();
114
    
115
    /**
116
     * Get the placement group name.
117
     * @return Name of the placement group
118
     */
119
    String getName();
120
    
121
    /**
122
     * Get the resource bundles.
123
     * @return List of resource bundle maps
124
     */
125
    List<Map<String, Double>> getBundles();
126
    
127
    /**
128
     * Get the placement strategy.
129
     * @return PlacementStrategy used by this group
130
     */
131
    PlacementStrategy getStrategy();
132
    
133
    /**
134
     * Get the current state.
135
     * @return Current PlacementGroupState
136
     */
137
    PlacementGroupState getState();
138
    
139
    /**
140
     * Wait for the placement group to be ready.
141
     * @param timeoutSeconds Maximum time to wait in seconds
142
     * @return true if ready within timeout, false otherwise
143
     */
144
    boolean wait(int timeoutSeconds);
145
}
146
```
147

148
**Usage Examples:**
149

150
```java
151
public class PlacementGroupInfo {
152
    public static void main(String[] args) {
153
        Ray.init();
154
        
155
        // Create placement group
156
        PlacementGroup pg = createExamplePlacementGroup();
157
        
158
        // Get placement group information
159
        System.out.println("ID: " + pg.getId());
160
        System.out.println("Name: " + pg.getName());
161
        System.out.println("Strategy: " + pg.getStrategy());
162
        System.out.println("State: " + pg.getState());
163
        
164
        // Inspect resource bundles
165
        List<Map<String, Double>> bundles = pg.getBundles();
166
        for (int i = 0; i < bundles.size(); i++) {
167
            System.out.println("Bundle " + i + ": " + bundles.get(i));
168
        }
169
        
170
        // Wait for ready state
171
        if (pg.wait(30)) {
172
            System.out.println("Placement group is ready for use");
173
        }
174
        
175
        Ray.shutdown();
176
    }
177
    
178
    private static PlacementGroup createExamplePlacementGroup() {
179
        List<Map<String, Double>> bundles = Arrays.asList(
180
            Map.of("CPU", 4.0),
181
            Map.of("CPU", 2.0, "GPU", 1.0)
182
        );
183
        
184
        PlacementGroupCreationOptions options = PlacementGroupCreationOptions.builder()
185
            .setName("example-group")
186
            .setBundles(bundles)
187
            .setStrategy(PlacementStrategy.PACK)
188
            .build();
189
        
190
        return PlacementGroups.createPlacementGroup(options);
191
    }
192
}
193
```
194

195
### Placement Strategies
196

197
Control how resources are allocated across the cluster.
198

199
```java { .api }
200
public enum PlacementStrategy {
201
    /**
202
     * Pack bundles on as few nodes as possible.
203
     */
204
    PACK,
205
    
206
    /**
207
     * Spread bundles across as many nodes as possible.
208
     */
209
    SPREAD,
210
    
211
    /**
212
     * Pack bundles on as few nodes as possible (strict).
213
     * Fails if cannot pack all bundles.
214
     */
215
    STRICT_PACK,
216
    
217
    /**
218
     * Spread bundles across different nodes (strict).
219
     * Fails if cannot spread across enough nodes.
220
     */
221
    STRICT_SPREAD
222
}
223
```
224

225
**Usage Examples:**
226

227
```java
228
public class PlacementStrategies {
229
    public static void main(String[] args) {
230
        Ray.init();
231
        
232
        // PACK strategy - minimize node usage
233
        PlacementGroup packGroup = createPlacementGroup("pack-group", PlacementStrategy.PACK);
234
        
235
        // SPREAD strategy - maximize distribution
236
        PlacementGroup spreadGroup = createPlacementGroup("spread-group", PlacementStrategy.SPREAD);
237
        
238
        // STRICT_PACK - fail if cannot pack on few nodes
239
        PlacementGroup strictPackGroup = createPlacementGroup("strict-pack", PlacementStrategy.STRICT_PACK);
240
        
241
        // STRICT_SPREAD - fail if cannot spread across many nodes
242
        PlacementGroup strictSpreadGroup = createPlacementGroup("strict-spread", PlacementStrategy.STRICT_SPREAD);
243
        
244
        Ray.shutdown();
245
    }
246
    
247
    private static PlacementGroup createPlacementGroup(String name, PlacementStrategy strategy) {
248
        List<Map<String, Double>> bundles = Arrays.asList(
249
            Map.of("CPU", 2.0),
250
            Map.of("CPU", 2.0),
251
            Map.of("CPU", 2.0)
252
        );
253
        
254
        PlacementGroupCreationOptions options = PlacementGroupCreationOptions.builder()
255
            .setName(name)
256
            .setBundles(bundles)
257
            .setStrategy(strategy)
258
            .build();
259
        
260
        return PlacementGroups.createPlacementGroup(options);
261
    }
262
}
263
```
264

265
### Placement Group States
266

267
Monitor placement group lifecycle states.
268

269
```java { .api }
270
public enum PlacementGroupState {
271
    /**
272
     * Placement group is being created.
273
     */
274
    PENDING,
275
    
276
    /**
277
     * Placement group has been successfully created and is ready.
278
     */
279
    CREATED,
280
    
281
    /**
282
     * Placement group has been removed.
283
     */
284
    REMOVED
285
}
286
```
287

288
**Usage Example:**
289

290
```java
291
public class PlacementGroupStateMonitoring {
292
    public static void main(String[] args) {
293
        Ray.init();
294
        
295
        PlacementGroup pg = createExamplePlacementGroup();
296
        
297
        // Monitor state changes
298
        while (pg.getState() == PlacementGroupState.PENDING) {
299
            System.out.println("Placement group is still pending...");
300
            try {
301
                Thread.sleep(1000);
302
            } catch (InterruptedException e) {
303
                Thread.currentThread().interrupt();
304
                break;
305
            }
306
        }
307
        
308
        switch (pg.getState()) {
309
            case CREATED:
310
                System.out.println("Placement group created successfully");
311
                break;
312
            case REMOVED:
313
                System.out.println("Placement group was removed");
314
                break;
315
            case PENDING:
316
                System.out.println("Placement group still pending");
317
                break;
318
        }
319
        
320
        Ray.shutdown();
321
    }
322
}
323
```
324

325
### Placement Group Creation Options
326

327
Configure placement group creation with detailed options.
328

329
```java { .api }
330
public class PlacementGroupCreationOptions {
331
    /**
332
     * Get builder for creating options.
333
     * @return PlacementGroupCreationOptions.Builder
334
     */
335
    public static Builder builder();
336
    
337
    public static class Builder {
338
        /**
339
         * Set placement group name.
340
         * @param name Name for the placement group
341
         * @return Builder for method chaining
342
         */
343
        public Builder setName(String name);
344
        
345
        /**
346
         * Set resource bundles.
347
         * @param bundles List of resource bundle maps
348
         * @return Builder for method chaining
349
         */
350
        public Builder setBundles(List<Map<String, Double>> bundles);
351
        
352
        /**
353
         * Set placement strategy.
354
         * @param strategy PlacementStrategy to use
355
         * @return Builder for method chaining
356
         */
357
        public Builder setStrategy(PlacementStrategy strategy);
358
        
359
        /**
360
         * Set placement group lifetime.
361
         * @param lifetime Lifetime setting
362
         * @return Builder for method chaining
363
         */
364
        public Builder setLifetime(ActorLifetime lifetime);
365
        
366
        /**
367
         * Build the options.
368
         * @return PlacementGroupCreationOptions instance
369
         */
370
        public PlacementGroupCreationOptions build();
371
    }
372
}
373
```
374

375
**Usage Example:**
376

377
```java
378
public class PlacementGroupConfiguration {
379
    public static void main(String[] args) {
380
        Ray.init();
381
        
382
        // Complex placement group configuration
383
        List<Map<String, Double>> bundles = Arrays.asList(
384
            // GPU-intensive bundle
385
            Map.of("CPU", 4.0, "GPU", 2.0, "memory", 8000.0),
386
            // CPU-intensive bundle
387
            Map.of("CPU", 8.0, "memory", 4000.0),
388
            // Storage bundle
389
            Map.of("CPU", 2.0, "storage", 1000.0)
390
        );
391
        
392
        PlacementGroupCreationOptions options = PlacementGroupCreationOptions.builder()
393
            .setName("complex-ml-pipeline")
394
            .setBundles(bundles)
395
            .setStrategy(PlacementStrategy.STRICT_PACK)
396
            .setLifetime(ActorLifetime.DETACHED)
397
            .build();
398
        
399
        PlacementGroup pg = PlacementGroups.createPlacementGroup(options);
400
        
401
        if (pg.wait(60)) {
402
            System.out.println("Complex placement group ready");
403
            
404
            // Use different bundles for different types of work
405
            // Bundle 0: GPU training tasks
406
            // Bundle 1: CPU preprocessing tasks  
407
            // Bundle 2: Storage and I/O tasks
408
            
409
        } else {
410
            System.out.println("Failed to create placement group within timeout");
411
        }
412
        
413
        Ray.shutdown();
414
    }
415
}
416
```
417

418
## Using Placement Groups with Tasks and Actors
419

420
### Task Placement
421

422
```java
423
public class TaskPlacement {
424
    public static String gpuTask(String data) {
425
        // GPU-intensive computation
426
        return "GPU processed: " + data;
427
    }
428
    
429
    public static String cpuTask(String data) {
430
        // CPU-intensive computation
431
        return "CPU processed: " + data;
432
    }
433
    
434
    public static void main(String[] args) {
435
        Ray.init();
436
        
437
        // Create placement group
438
        List<Map<String, Double>> bundles = Arrays.asList(
439
            Map.of("CPU", 2.0, "GPU", 1.0),  // Bundle 0: GPU bundle
440
            Map.of("CPU", 4.0)               // Bundle 1: CPU bundle
441
        );
442
        
443
        PlacementGroupCreationOptions options = PlacementGroupCreationOptions.builder()
444
            .setName("task-placement-group")
445
            .setBundles(bundles)
446
            .setStrategy(PlacementStrategy.STRICT_PACK)
447
            .build();
448
        
449
        PlacementGroup pg = PlacementGroups.createPlacementGroup(options);
450
        pg.wait(30);
451
        
452
        // Schedule tasks to specific bundles
453
        // Note: Actual bundle specification would be done through task options
454
        // This shows the conceptual approach
455
        
456
        // GPU tasks on bundle 0
457
        ObjectRef<String> gpuResult1 = Ray.task(TaskPlacement::gpuTask, "data1").remote();
458
        ObjectRef<String> gpuResult2 = Ray.task(TaskPlacement::gpuTask, "data2").remote();
459
        
460
        // CPU tasks on bundle 1
461
        ObjectRef<String> cpuResult1 = Ray.task(TaskPlacement::cpuTask, "data3").remote();
462
        ObjectRef<String> cpuResult2 = Ray.task(TaskPlacement::cpuTask, "data4").remote();
463
        
464
        // Get results
465
        System.out.println(Ray.get(gpuResult1));
466
        System.out.println(Ray.get(gpuResult2));
467
        System.out.println(Ray.get(cpuResult1));
468
        System.out.println(Ray.get(cpuResult2));
469
        
470
        PlacementGroups.removePlacementGroup(pg.getId());
471
        Ray.shutdown();
472
    }
473
}
474
```
475

476
### Actor Placement
477

478
```java
479
public class GpuActor {
480
    public String processWithGpu(String data) {
481
        return "GPU actor processed: " + data;
482
    }
483
}
484

485
public class CpuActor {
486
    public String processWithCpu(String data) {
487
        return "CPU actor processed: " + data;
488
    }
489
}
490

491
public class ActorPlacement {
492
    public static void main(String[] args) {
493
        Ray.init();
494
        
495
        // Create placement group for co-located actors
496
        List<Map<String, Double>> bundles = Arrays.asList(
497
            Map.of("CPU", 2.0, "GPU", 1.0),  // GPU actor bundle
498
            Map.of("CPU", 2.0)               // CPU actor bundle
499
        );
500
        
501
        PlacementGroupCreationOptions options = PlacementGroupCreationOptions.builder()
502
            .setName("actor-placement-group")
503
            .setBundles(bundles)
504
            .setStrategy(PlacementStrategy.PACK)
505
            .build();
506
        
507
        PlacementGroup pg = PlacementGroups.createPlacementGroup(options);
508
        pg.wait(30);
509
        
510
        // Create actors in specific bundles
511
        // Note: Actual bundle assignment would be done through actor creation options
512
        ActorHandle<GpuActor> gpuActor = Ray.actor(GpuActor::new).remote(); // Bundle 0
513
        ActorHandle<CpuActor> cpuActor = Ray.actor(CpuActor::new).remote();  // Bundle 1
514
        
515
        // Actors are co-located according to placement strategy
516
        ObjectRef<String> gpuResult = gpuActor.task(GpuActor::processWithGpu, "gpu-data").remote();
517
        ObjectRef<String> cpuResult = cpuActor.task(CpuActor::processWithCpu, "cpu-data").remote();
518
        
519
        System.out.println(Ray.get(gpuResult));
520
        System.out.println(Ray.get(cpuResult));
521
        
522
        PlacementGroups.removePlacementGroup(pg.getId());
523
        Ray.shutdown();
524
    }
525
}
526
```
527

528
## Best Practices
529

530
### Resource Planning
531

532
```java
533
// Plan resources based on workload requirements
534
List<Map<String, Double>> balancedBundles = Arrays.asList(
535
    // Training bundle
536
    Map.of("CPU", 4.0, "GPU", 2.0, "memory", 16000.0),
537
    // Preprocessing bundle  
538
    Map.of("CPU", 8.0, "memory", 8000.0),
539
    // Inference bundle
540
    Map.of("CPU", 2.0, "GPU", 1.0, "memory", 4000.0)
541
);
542
```
543

544
### Error Handling
545

546
```java
547
try {
548
    PlacementGroup pg = PlacementGroups.createPlacementGroup(options);
549
    
550
    if (!pg.wait(60)) {
551
        throw new RuntimeException("Placement group creation timed out");
552
    }
553
    
554
    // Use placement group...
555
    
556
} catch (Exception e) {
557
    System.err.println("Placement group error: " + e.getMessage());
558
} finally {
559
    // Always clean up placement groups
560
    if (pg != null) {
561
        PlacementGroups.removePlacementGroup(pg.getId());
562
    }
563
}
564
```
565

566
### Monitoring and Debugging
567

568
```java
569
public class PlacementGroupMonitoring {
570
    public static void main(String[] args) {
571
        Ray.init();
572
        
573
        // List all placement groups
574
        List<PlacementGroup> allGroups = PlacementGroups.getAllPlacementGroups();
575
        System.out.println("Active placement groups: " + allGroups.size());
576
        
577
        for (PlacementGroup pg : allGroups) {
578
            System.out.println("Group: " + pg.getName() + 
579
                             " State: " + pg.getState() + 
580
                             " Strategy: " + pg.getStrategy());
581
        }
582
        
583
        Ray.shutdown();
584
    }
585
}
586
```