CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-io-ray--ray-runtime

Ray runtime implementation for Java - the core distributed runtime component of Ray framework for scaling AI and Python applications

—

Pending
Overview
Eval results
Files

placement-groups.mddocs/

Placement Groups

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

Capabilities

Placement Group Management

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

public class PlacementGroups {
    /**
     * Create a new placement group.
     * @param options Configuration for the placement group
     * @return PlacementGroup instance
     */
    public static PlacementGroup createPlacementGroup(PlacementGroupCreationOptions options);
    
    /**
     * Get placement group by ID.
     * @param id Placement group ID
     * @return PlacementGroup instance or null if not found
     */
    public static PlacementGroup getPlacementGroup(PlacementGroupId id);
    
    /**
     * Get placement group by name.
     * @param name Placement group name
     * @return PlacementGroup instance or null if not found
     */
    public static PlacementGroup getPlacementGroup(String name);
    
    /**
     * Get placement group by name and namespace.
     * @param name Placement group name
     * @param namespace Namespace to search in
     * @return PlacementGroup instance or null if not found
     */
    public static PlacementGroup getPlacementGroup(String name, String namespace);
    
    /**
     * Get all placement groups in the cluster.
     * @return List of all placement groups
     */
    public static List<PlacementGroup> getAllPlacementGroups();
    
    /**
     * Remove a placement group.
     * @param id Placement group ID to remove
     */
    public static void removePlacementGroup(PlacementGroupId id);
}

Usage Examples:

import io.ray.api.Ray;
import io.ray.api.PlacementGroups;
import io.ray.api.placementgroup.PlacementGroup;
import io.ray.api.placementgroup.PlacementStrategy;
import io.ray.api.options.PlacementGroupCreationOptions;

public class PlacementGroupExample {
    public static void main(String[] args) {
        Ray.init();
        
        // Define resource bundles
        List<Map<String, Double>> bundles = Arrays.asList(
            Map.of("CPU", 2.0, "GPU", 1.0),  // Bundle 1: 2 CPUs, 1 GPU
            Map.of("CPU", 2.0),              // Bundle 2: 2 CPUs
            Map.of("CPU", 1.0)               // Bundle 3: 1 CPU
        );
        
        // Create placement group options
        PlacementGroupCreationOptions options = PlacementGroupCreationOptions.builder()
            .setName("ml-training-group")
            .setBundles(bundles)
            .setStrategy(PlacementStrategy.STRICT_PACK)
            .build();
        
        // Create placement group
        PlacementGroup pg = PlacementGroups.createPlacementGroup(options);
        
        // Wait for placement group to be ready
        boolean ready = pg.wait(30); // Wait up to 30 seconds
        if (ready) {
            System.out.println("Placement group ready: " + pg.getId());
        } else {
            System.out.println("Placement group creation timed out");
        }
        
        // Use placement group for tasks and actors...
        
        // Clean up
        PlacementGroups.removePlacementGroup(pg.getId());
        
        Ray.shutdown();
    }
}

Placement Group Interface

Core placement group operations and information access.

public interface PlacementGroup {
    /**
     * Get the placement group ID.
     * @return PlacementGroupId
     */
    PlacementGroupId getId();
    
    /**
     * Get the placement group name.
     * @return Name of the placement group
     */
    String getName();
    
    /**
     * Get the resource bundles.
     * @return List of resource bundle maps
     */
    List<Map<String, Double>> getBundles();
    
    /**
     * Get the placement strategy.
     * @return PlacementStrategy used by this group
     */
    PlacementStrategy getStrategy();
    
    /**
     * Get the current state.
     * @return Current PlacementGroupState
     */
    PlacementGroupState getState();
    
    /**
     * Wait for the placement group to be ready.
     * @param timeoutSeconds Maximum time to wait in seconds
     * @return true if ready within timeout, false otherwise
     */
    boolean wait(int timeoutSeconds);
}

Usage Examples:

public class PlacementGroupInfo {
    public static void main(String[] args) {
        Ray.init();
        
        // Create placement group
        PlacementGroup pg = createExamplePlacementGroup();
        
        // Get placement group information
        System.out.println("ID: " + pg.getId());
        System.out.println("Name: " + pg.getName());
        System.out.println("Strategy: " + pg.getStrategy());
        System.out.println("State: " + pg.getState());
        
        // Inspect resource bundles
        List<Map<String, Double>> bundles = pg.getBundles();
        for (int i = 0; i < bundles.size(); i++) {
            System.out.println("Bundle " + i + ": " + bundles.get(i));
        }
        
        // Wait for ready state
        if (pg.wait(30)) {
            System.out.println("Placement group is ready for use");
        }
        
        Ray.shutdown();
    }
    
    private static PlacementGroup createExamplePlacementGroup() {
        List<Map<String, Double>> bundles = Arrays.asList(
            Map.of("CPU", 4.0),
            Map.of("CPU", 2.0, "GPU", 1.0)
        );
        
        PlacementGroupCreationOptions options = PlacementGroupCreationOptions.builder()
            .setName("example-group")
            .setBundles(bundles)
            .setStrategy(PlacementStrategy.PACK)
            .build();
        
        return PlacementGroups.createPlacementGroup(options);
    }
}

Placement Strategies

Control how resources are allocated across the cluster.

public enum PlacementStrategy {
    /**
     * Pack bundles on as few nodes as possible.
     */
    PACK,
    
    /**
     * Spread bundles across as many nodes as possible.
     */
    SPREAD,
    
    /**
     * Pack bundles on as few nodes as possible (strict).
     * Fails if cannot pack all bundles.
     */
    STRICT_PACK,
    
    /**
     * Spread bundles across different nodes (strict).
     * Fails if cannot spread across enough nodes.
     */
    STRICT_SPREAD
}

Usage Examples:

public class PlacementStrategies {
    public static void main(String[] args) {
        Ray.init();
        
        // PACK strategy - minimize node usage
        PlacementGroup packGroup = createPlacementGroup("pack-group", PlacementStrategy.PACK);
        
        // SPREAD strategy - maximize distribution
        PlacementGroup spreadGroup = createPlacementGroup("spread-group", PlacementStrategy.SPREAD);
        
        // STRICT_PACK - fail if cannot pack on few nodes
        PlacementGroup strictPackGroup = createPlacementGroup("strict-pack", PlacementStrategy.STRICT_PACK);
        
        // STRICT_SPREAD - fail if cannot spread across many nodes
        PlacementGroup strictSpreadGroup = createPlacementGroup("strict-spread", PlacementStrategy.STRICT_SPREAD);
        
        Ray.shutdown();
    }
    
    private static PlacementGroup createPlacementGroup(String name, PlacementStrategy strategy) {
        List<Map<String, Double>> bundles = Arrays.asList(
            Map.of("CPU", 2.0),
            Map.of("CPU", 2.0),
            Map.of("CPU", 2.0)
        );
        
        PlacementGroupCreationOptions options = PlacementGroupCreationOptions.builder()
            .setName(name)
            .setBundles(bundles)
            .setStrategy(strategy)
            .build();
        
        return PlacementGroups.createPlacementGroup(options);
    }
}

Placement Group States

Monitor placement group lifecycle states.

public enum PlacementGroupState {
    /**
     * Placement group is being created.
     */
    PENDING,
    
    /**
     * Placement group has been successfully created and is ready.
     */
    CREATED,
    
    /**
     * Placement group has been removed.
     */
    REMOVED
}

Usage Example:

public class PlacementGroupStateMonitoring {
    public static void main(String[] args) {
        Ray.init();
        
        PlacementGroup pg = createExamplePlacementGroup();
        
        // Monitor state changes
        while (pg.getState() == PlacementGroupState.PENDING) {
            System.out.println("Placement group is still pending...");
            try {
                Thread.sleep(1000);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                break;
            }
        }
        
        switch (pg.getState()) {
            case CREATED:
                System.out.println("Placement group created successfully");
                break;
            case REMOVED:
                System.out.println("Placement group was removed");
                break;
            case PENDING:
                System.out.println("Placement group still pending");
                break;
        }
        
        Ray.shutdown();
    }
}

Placement Group Creation Options

Configure placement group creation with detailed options.

public class PlacementGroupCreationOptions {
    /**
     * Get builder for creating options.
     * @return PlacementGroupCreationOptions.Builder
     */
    public static Builder builder();
    
    public static class Builder {
        /**
         * Set placement group name.
         * @param name Name for the placement group
         * @return Builder for method chaining
         */
        public Builder setName(String name);
        
        /**
         * Set resource bundles.
         * @param bundles List of resource bundle maps
         * @return Builder for method chaining
         */
        public Builder setBundles(List<Map<String, Double>> bundles);
        
        /**
         * Set placement strategy.
         * @param strategy PlacementStrategy to use
         * @return Builder for method chaining
         */
        public Builder setStrategy(PlacementStrategy strategy);
        
        /**
         * Set placement group lifetime.
         * @param lifetime Lifetime setting
         * @return Builder for method chaining
         */
        public Builder setLifetime(ActorLifetime lifetime);
        
        /**
         * Build the options.
         * @return PlacementGroupCreationOptions instance
         */
        public PlacementGroupCreationOptions build();
    }
}

Usage Example:

public class PlacementGroupConfiguration {
    public static void main(String[] args) {
        Ray.init();
        
        // Complex placement group configuration
        List<Map<String, Double>> bundles = Arrays.asList(
            // GPU-intensive bundle
            Map.of("CPU", 4.0, "GPU", 2.0, "memory", 8000.0),
            // CPU-intensive bundle
            Map.of("CPU", 8.0, "memory", 4000.0),
            // Storage bundle
            Map.of("CPU", 2.0, "storage", 1000.0)
        );
        
        PlacementGroupCreationOptions options = PlacementGroupCreationOptions.builder()
            .setName("complex-ml-pipeline")
            .setBundles(bundles)
            .setStrategy(PlacementStrategy.STRICT_PACK)
            .setLifetime(ActorLifetime.DETACHED)
            .build();
        
        PlacementGroup pg = PlacementGroups.createPlacementGroup(options);
        
        if (pg.wait(60)) {
            System.out.println("Complex placement group ready");
            
            // Use different bundles for different types of work
            // Bundle 0: GPU training tasks
            // Bundle 1: CPU preprocessing tasks  
            // Bundle 2: Storage and I/O tasks
            
        } else {
            System.out.println("Failed to create placement group within timeout");
        }
        
        Ray.shutdown();
    }
}

Using Placement Groups with Tasks and Actors

Task Placement

public class TaskPlacement {
    public static String gpuTask(String data) {
        // GPU-intensive computation
        return "GPU processed: " + data;
    }
    
    public static String cpuTask(String data) {
        // CPU-intensive computation
        return "CPU processed: " + data;
    }
    
    public static void main(String[] args) {
        Ray.init();
        
        // Create placement group
        List<Map<String, Double>> bundles = Arrays.asList(
            Map.of("CPU", 2.0, "GPU", 1.0),  // Bundle 0: GPU bundle
            Map.of("CPU", 4.0)               // Bundle 1: CPU bundle
        );
        
        PlacementGroupCreationOptions options = PlacementGroupCreationOptions.builder()
            .setName("task-placement-group")
            .setBundles(bundles)
            .setStrategy(PlacementStrategy.STRICT_PACK)
            .build();
        
        PlacementGroup pg = PlacementGroups.createPlacementGroup(options);
        pg.wait(30);
        
        // Schedule tasks to specific bundles
        // Note: Actual bundle specification would be done through task options
        // This shows the conceptual approach
        
        // GPU tasks on bundle 0
        ObjectRef<String> gpuResult1 = Ray.task(TaskPlacement::gpuTask, "data1").remote();
        ObjectRef<String> gpuResult2 = Ray.task(TaskPlacement::gpuTask, "data2").remote();
        
        // CPU tasks on bundle 1
        ObjectRef<String> cpuResult1 = Ray.task(TaskPlacement::cpuTask, "data3").remote();
        ObjectRef<String> cpuResult2 = Ray.task(TaskPlacement::cpuTask, "data4").remote();
        
        // Get results
        System.out.println(Ray.get(gpuResult1));
        System.out.println(Ray.get(gpuResult2));
        System.out.println(Ray.get(cpuResult1));
        System.out.println(Ray.get(cpuResult2));
        
        PlacementGroups.removePlacementGroup(pg.getId());
        Ray.shutdown();
    }
}

Actor Placement

public class GpuActor {
    public String processWithGpu(String data) {
        return "GPU actor processed: " + data;
    }
}

public class CpuActor {
    public String processWithCpu(String data) {
        return "CPU actor processed: " + data;
    }
}

public class ActorPlacement {
    public static void main(String[] args) {
        Ray.init();
        
        // Create placement group for co-located actors
        List<Map<String, Double>> bundles = Arrays.asList(
            Map.of("CPU", 2.0, "GPU", 1.0),  // GPU actor bundle
            Map.of("CPU", 2.0)               // CPU actor bundle
        );
        
        PlacementGroupCreationOptions options = PlacementGroupCreationOptions.builder()
            .setName("actor-placement-group")
            .setBundles(bundles)
            .setStrategy(PlacementStrategy.PACK)
            .build();
        
        PlacementGroup pg = PlacementGroups.createPlacementGroup(options);
        pg.wait(30);
        
        // Create actors in specific bundles
        // Note: Actual bundle assignment would be done through actor creation options
        ActorHandle<GpuActor> gpuActor = Ray.actor(GpuActor::new).remote(); // Bundle 0
        ActorHandle<CpuActor> cpuActor = Ray.actor(CpuActor::new).remote();  // Bundle 1
        
        // Actors are co-located according to placement strategy
        ObjectRef<String> gpuResult = gpuActor.task(GpuActor::processWithGpu, "gpu-data").remote();
        ObjectRef<String> cpuResult = cpuActor.task(CpuActor::processWithCpu, "cpu-data").remote();
        
        System.out.println(Ray.get(gpuResult));
        System.out.println(Ray.get(cpuResult));
        
        PlacementGroups.removePlacementGroup(pg.getId());
        Ray.shutdown();
    }
}

Best Practices

Resource Planning

// Plan resources based on workload requirements
List<Map<String, Double>> balancedBundles = Arrays.asList(
    // Training bundle
    Map.of("CPU", 4.0, "GPU", 2.0, "memory", 16000.0),
    // Preprocessing bundle  
    Map.of("CPU", 8.0, "memory", 8000.0),
    // Inference bundle
    Map.of("CPU", 2.0, "GPU", 1.0, "memory", 4000.0)
);

Error Handling

try {
    PlacementGroup pg = PlacementGroups.createPlacementGroup(options);
    
    if (!pg.wait(60)) {
        throw new RuntimeException("Placement group creation timed out");
    }
    
    // Use placement group...
    
} catch (Exception e) {
    System.err.println("Placement group error: " + e.getMessage());
} finally {
    // Always clean up placement groups
    if (pg != null) {
        PlacementGroups.removePlacementGroup(pg.getId());
    }
}

Monitoring and Debugging

public class PlacementGroupMonitoring {
    public static void main(String[] args) {
        Ray.init();
        
        // List all placement groups
        List<PlacementGroup> allGroups = PlacementGroups.getAllPlacementGroups();
        System.out.println("Active placement groups: " + allGroups.size());
        
        for (PlacementGroup pg : allGroups) {
            System.out.println("Group: " + pg.getName() + 
                             " State: " + pg.getState() + 
                             " Strategy: " + pg.getStrategy());
        }
        
        Ray.shutdown();
    }
}

Install with Tessl CLI

npx tessl i tessl/maven-io-ray--ray-runtime

docs

actors.md

advanced-actors.md

cross-language.md

index.md

object-store.md

placement-groups.md

runtime.md

tasks.md

tile.json