Implementation:Ray project Ray PlacementGroup Interface

Knowledge Sources	Ray
Domains	Distributed_Computing, Java_API
Last Updated	2026-02-13 16:00 GMT

Overview

Public API interface defining the contract for placement groups in the Ray Java API.

Description

PlacementGroup is a Java interface that defines the API for placement groups, which are used to co-locate or distribute interdependent actors across cluster nodes according to a chosen scheduling strategy. It declares methods to retrieve the placement group's identity (getId, getName), its resource bundles (getBundles), its scheduling strategy (getStrategy), its lifecycle state (getState), and a blocking wait method that blocks until the group is ready or a timeout elapses. A placement group consists of one or more bundles plus a specific PlacementStrategy.

Usage

Use this interface to interact with placement groups after they have been created. All concrete placement group implementations must satisfy this interface, enabling users to reserve and query grouped resource allocations for actor scheduling without coupling to a specific runtime implementation.

Code Reference

Source Location

• Repository: Ray
• File: java/api/src/main/java/io/ray/api/placementgroup/PlacementGroup.java

Signature

public interface PlacementGroup {
    PlacementGroupId getId();
    String getName();
    List<Map<String, Double>> getBundles();
    PlacementStrategy getStrategy();
    PlacementGroupState getState();
    boolean wait(int timeoutSeconds);
}

Import

import io.ray.api.placementgroup.PlacementGroup;

I/O Contract

Inputs

Name	Type	Required	Description
timeoutSeconds	int	Yes	Timeout in seconds for the wait method

Outputs

Name	Type	Description
id	PlacementGroupId	Unique identifier of the placement group
name	String	Name of the placement group
bundles	List<Map<String, Double>>	Resource bundles (resource name to quantity maps)
strategy	PlacementStrategy	The scheduling strategy (PACK, SPREAD, etc.)
state	PlacementGroupState	Current creation state of the placement group
ready	boolean	Whether the placement group is ready (from wait)

Usage Examples

// Create and use a placement group
PlacementGroup pg = PlacementGroups.createPlacementGroup(options);

// Wait for the group to be ready
boolean ready = pg.wait(60);
if (ready) {
    // Inspect the placement group
    System.out.println("Group: " + pg.getName());
    System.out.println("Strategy: " + pg.getStrategy());
    System.out.println("State: " + pg.getState());
    System.out.println("Bundles: " + pg.getBundles());

    // Use the placement group for actor creation
    ActorHandle<MyActor> actor = Ray.actor(MyActor::new)
        .setPlacementGroup(pg, 0)
        .remote();
}

Related Pages

• Environment:Ray_project_Ray_Java_Build_Environment