Implementation:Ray project Ray PlacementGroups API

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

Overview

Public API class for managing Ray placement groups provided by the Ray Java API.

Description

PlacementGroups is a stateless facade that provides static methods for the complete lifecycle of placement groups, which control how actors and tasks are co-located across cluster nodes according to resource constraints and placement strategies. All methods delegate to Ray.internal() (the runtime): createPlacementGroup() sends an asynchronous request to GCS to preallocate resources, getPlacementGroup() retrieves groups by ID, name, or name+namespace, getAllPlacementGroups() lists all groups in the cluster, and removePlacementGroup() deletes a group by ID.

Usage

Use this class when you need to create, retrieve, list, or remove placement groups for workloads that require co-location of resources, such as gang scheduling for distributed training.

Code Reference

Source Location

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

Signature

public class PlacementGroups {
    public static PlacementGroup createPlacementGroup(PlacementGroupCreationOptions creationOptions);
    public static PlacementGroup getPlacementGroup(PlacementGroupId id);
    public static PlacementGroup getPlacementGroup(String name);
    public static PlacementGroup getPlacementGroup(String name, String namespace);
    public static List<PlacementGroup> getAllPlacementGroups();
    public static void removePlacementGroup(PlacementGroupId id);
}

Import

import io.ray.api.PlacementGroups;

I/O Contract

Inputs

Name	Type	Required	Description
creationOptions	PlacementGroupCreationOptions	Yes	Configuration for creating a placement group (bundles, strategy, name)
id	PlacementGroupId	Yes	Identifier of an existing placement group (for get/remove)
name	String	Yes	Name of a named placement group (for get by name)
namespace	String	No	Namespace of the placement group (for cross-namespace lookup)

Outputs

Name	Type	Description
placementGroup	PlacementGroup	Handle to the created or retrieved placement group
allGroups	List<PlacementGroup>	List of all placement groups in the cluster

Usage Examples

// Create a placement group with two bundles
PlacementGroupCreationOptions options = new PlacementGroupCreationOptions.Builder()
    .setName("my-group")
    .setBundles(Arrays.asList(
        ImmutableMap.of("CPU", 1.0),
        ImmutableMap.of("CPU", 1.0)))
    .setStrategy(PlacementStrategy.PACK)
    .build();
PlacementGroup pg = PlacementGroups.createPlacementGroup(options);

// Retrieve a placement group by name
PlacementGroup pg2 = PlacementGroups.getPlacementGroup("my-group");

// List all placement groups
List<PlacementGroup> allGroups = PlacementGroups.getAllPlacementGroups();

// Remove a placement group
PlacementGroups.removePlacementGroup(pg.getId());

Related Pages

• Environment:Ray_project_Ray_Java_Build_Environment