Add placement group java api (#9611)

* add part code

* add part code

* add part code

* fix code style

* fix review comment

* fix review comment

* add part code

* add part code

* add part code

* add part code

* fix review comment

* fix review comment

* fix code style

* fix review comment

* fix lint error

* fix lint error

Co-authored-by: 灵洵 <fengbin.ffb@antfin.com>

java/api/src/main/java/io/ray/api/Ray.java

@@ -2,11 +2,14 @@ package io.ray.api;
 
 import io.ray.api.id.ObjectId;
 import io.ray.api.id.UniqueId;
+import io.ray.api.placementgroup.PlacementGroup;
+import io.ray.api.placementgroup.PlacementStrategy;
 import io.ray.api.runtime.RayRuntime;
 import io.ray.api.runtime.RayRuntimeFactory;
 import io.ray.api.runtimecontext.RuntimeContext;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 import java.util.concurrent.Callable;
 
@@ -240,4 +243,22 @@ public final class Ray extends RayCall {
   public static RuntimeContext getRuntimeContext() {
     return runtime.getRuntimeContext();
   }
+
+  /**
+   * Create a placement group.
+   * A placement group is used to place actors according to a specific strategy
+   * and resource constraints.
+   * It will sends a request to GCS to preallocate the specified resources, which is asynchronous.
+   * If the specified resource cannot be allocated, it will wait for the resource
+   * to be updated and rescheduled.
+   * This function only works when gcs actor manager is turned on.
+   *
+   * @param bundles Preallocated resource list.
+   * @param strategy Actor placement strategy.
+   * @return A handle to the created placement group.
+   */
+  public static PlacementGroup createPlacementGroup(List<Map<String, Double>> bundles,
+      PlacementStrategy strategy) {
+    return runtime.createPlacementGroup(bundles, strategy);
+  }
 }

java/api/src/main/java/io/ray/api/call/BaseActorCreator.java

@@ -2,6 +2,7 @@ package io.ray.api.call;
 
 import io.ray.api.Ray;
 import io.ray.api.options.ActorCreationOptions;
+import io.ray.api.placementgroup.PlacementGroup;
 import java.util.Map;
 
 /**
@@ -85,7 +86,6 @@ public class BaseActorCreator<T extends BaseActorCreator> {
   }
 
   /**
-   * /**
    * Set the max number of concurrent calls to allow for this actor.
    * <p>
    * The max concurrency defaults to 1 for threaded execution.
@@ -100,6 +100,19 @@ public class BaseActorCreator<T extends BaseActorCreator> {
     return self();
   }
 
+  /**
+   * Set the placement group to place this actor in.
+   *
+   * @param group The placement group of the actor.
+   * @param bundleIndex The index of the bundle to place this actor in.
+   * @return self
+   * @see ActorCreationOptions.Builder#setPlacementGroup(PlacementGroup, int)
+   */
+  public T setPlacementGroup(PlacementGroup group, int bundleIndex) {
+    builder.setPlacementGroup(group, bundleIndex);
+    return self();
+  }
+
   @SuppressWarnings("unchecked")
   private T self() {
     return (T) this;

java/api/src/main/java/io/ray/api/options/ActorCreationOptions.java

@@ -1,6 +1,7 @@
 package io.ray.api.options;
 
 import io.ray.api.Ray;
+import io.ray.api.placementgroup.PlacementGroup;
 import java.util.HashMap;
 import java.util.Map;
 
@@ -13,15 +14,20 @@ public class ActorCreationOptions extends BaseTaskOptions {
   public final int maxRestarts;
   public final String jvmOptions;
   public final int maxConcurrency;
+  public final PlacementGroup group;
+  public final int bundleIndex;
 
   private ActorCreationOptions(boolean global, String name, Map<String, Double> resources,
-                               int maxRestarts, String jvmOptions, int maxConcurrency) {
+                               int maxRestarts, String jvmOptions, int maxConcurrency,
+                               PlacementGroup group, int bundleIndex) {
     super(resources);
     this.global = global;
     this.name = name;
     this.maxRestarts = maxRestarts;
     this.jvmOptions = jvmOptions;
     this.maxConcurrency = maxConcurrency;
+    this.group = group;
+    this.bundleIndex = bundleIndex;
   }
 
   /**
@@ -34,6 +40,8 @@ public class ActorCreationOptions extends BaseTaskOptions {
     private int maxRestarts = 0;
     private String jvmOptions = null;
     private int maxConcurrency = 1;
+    private PlacementGroup group;
+    private int bundleIndex;
 
     /**
      * Set the actor name of a named actor.
@@ -135,9 +143,22 @@ public class ActorCreationOptions extends BaseTaskOptions {
       return this;
     }
 
+    /**
+     * Set the placement group to place this actor in.
+     *
+     * @param group The placement group of the actor.
+     * @param bundleIndex The index of the bundle to place this actor in.
+     * @return self
+     */
+    public Builder setPlacementGroup(PlacementGroup group, int bundleIndex) {
+      this.group = group;
+      this.bundleIndex = bundleIndex;
+      return this;
+    }
+
     public ActorCreationOptions build() {
       return new ActorCreationOptions(
-          global, name, resources, maxRestarts, jvmOptions, maxConcurrency);
+          global, name, resources, maxRestarts, jvmOptions, maxConcurrency, group, bundleIndex);
     }
   }
 

java/api/src/main/java/io/ray/api/placementgroup/PlacementGroup.java

@@ -0,0 +1,10 @@
+package io.ray.api.placementgroup;
+
+/**
+ * A placement group is used to place interdependent actors according to a specific strategy
+ * {@link PlacementStrategy}.
+ * When a placement group is created, the corresponding actor slots and resources are preallocated.
+ * A placement group consists of one or more bundles plus a specific placement strategy.
+ */
+public interface PlacementGroup {
+}

java/api/src/main/java/io/ray/api/placementgroup/PlacementStrategy.java

@@ -0,0 +1,25 @@
+package io.ray.api.placementgroup;
+
+/**
+ * The actor placement strategy.
+ */
+public enum PlacementStrategy {
+  /**
+   * Packs Bundles close together inside nodes as tight as possible.
+   */
+  PACK(0),
+  /**
+   * Places Bundles across distinct nodes as even as possible.
+   */
+  SPREAD(1);
+
+  private int value = 0;
+
+  PlacementStrategy(int value) {
+    this.value = value;
+  }
+
+  public int value() {
+    return this.value;
+  }
+}

java/api/src/main/java/io/ray/api/runtime/RayRuntime.java

@@ -14,8 +14,11 @@ import io.ray.api.id.ObjectId;
 import io.ray.api.id.UniqueId;
 import io.ray.api.options.ActorCreationOptions;
 import io.ray.api.options.CallOptions;
+import io.ray.api.placementgroup.PlacementGroup;
+import io.ray.api.placementgroup.PlacementStrategy;
 import io.ray.api.runtimecontext.RuntimeContext;
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 import java.util.concurrent.Callable;
 
@@ -169,6 +172,9 @@ public interface RayRuntime {
   PyActorHandle createActor(PyActorClass pyActorClass, Object[] args,
                             ActorCreationOptions options);
 
+  PlacementGroup createPlacementGroup(List<Map<String, Double>> bundles,
+      PlacementStrategy strategy);
+
   RuntimeContext getRuntimeContext();
 
   Object getAsyncContext();