Mark the new passivation strategies as may change (#30999)

akka-cluster-sharding-typed/src/main/scala/akka/cluster/sharding/typed/ClusterShardingSettings.scala

@@ -163,6 +163,9 @@ object ClusterShardingSettings {
   }
   case object RememberEntitiesStoreModeDData extends RememberEntitiesStoreMode { override def name = "ddata" }
 
+  /**
+   * API MAY CHANGE: Settings for passivation strategies may change after additional testing and feedback.
+   */
   @ApiMayChange
   final class PassivationStrategySettings private (
       val idleEntitySettings: Option[PassivationStrategySettings.IdleSettings],
@@ -225,6 +228,10 @@ object ClusterShardingSettings {
       new PassivationStrategySettings(idleEntitySettings, activeEntityLimit, replacementPolicySettings, oldSettingUsed)
   }
 
+  /**
+   * API MAY CHANGE: Settings for passivation strategies may change after additional testing and feedback.
+   */
+  @ApiMayChange
   object PassivationStrategySettings {
     import ClassicShardingSettings.{ PassivationStrategySettings => ClassicPassivationStrategySettings }
 
@@ -705,6 +712,10 @@ final class ClusterShardingSettings(
   def withPassivateIdleEntityAfter(duration: java.time.Duration): ClusterShardingSettings =
     copy(passivationStrategySettings = passivationStrategySettings.withOldIdleStrategy(duration.asScala))
 
+  /**
+   * API MAY CHANGE: Settings for passivation strategies may change after additional testing and feedback.
+   */
+  @ApiMayChange
   def withPassivationStrategy(settings: ClusterShardingSettings.PassivationStrategySettings): ClusterShardingSettings =
     copy(passivationStrategySettings = settings)
 

akka-cluster-sharding/src/main/resources/reference.conf

@@ -42,6 +42,9 @@ akka.cluster.sharding {
     # Set to "default-strategy" to switch to the recommended default strategy with an active entity limit.
     # See the strategy-defaults section for possible passivation strategy settings and default values.
     # Passivation strategies are always disabled if `remember-entities` is enabled.
+    #
+    # API MAY CHANGE: Configuration for passivation strategies, except default-idle-strategy,
+    # may change after additional testing and feedback.
     strategy = "default-idle-strategy"
 
     # Default passivation strategy without active entity limit; time out idle entities after 2 minutes.

akka-cluster-sharding/src/main/scala/akka/cluster/sharding/ClusterShardingSettings.scala

@@ -129,6 +129,9 @@ object ClusterShardingSettings {
   private[akka] def roleOption(role: String): Option[String] =
     if (role == "") None else Option(role)
 
+  /**
+   * API MAY CHANGE: Settings for passivation strategies may change after additional testing and feedback.
+   */
   @ApiMayChange
   final class PassivationStrategySettings private[akka] (
       val idleEntitySettings: Option[PassivationStrategySettings.IdleSettings],
@@ -191,6 +194,10 @@ object ClusterShardingSettings {
       new PassivationStrategySettings(idleEntitySettings, activeEntityLimit, replacementPolicySettings, oldSettingUsed)
   }
 
+  /**
+   * API MAY CHANGE: Settings for passivation strategies may change after additional testing and feedback.
+   */
+  @ApiMayChange
   object PassivationStrategySettings {
     val defaults = new PassivationStrategySettings(
       idleEntitySettings = None,
@@ -333,6 +340,11 @@ object ClusterShardingSettings {
         new LeastFrequentlyUsedSettings(dynamicAging)
     }
 
+    /**
+     * API MAY CHANGE: Settings and configuration for passivation strategies may change after additional
+     * testing and feedback.
+     */
+    @ApiMayChange
     def apply(config: Config): PassivationStrategySettings = {
       toRootLowerCase(config.getString("strategy")) match {
         case "off" | "none" => PassivationStrategySettings.disabled
@@ -371,16 +383,32 @@ object ClusterShardingSettings {
   @InternalApi
   private[akka] sealed trait PassivationStrategy
 
+  /**
+   * INTERNAL API
+   */
+  @InternalApi
   private[akka] case object NoPassivationStrategy extends PassivationStrategy
 
+  /**
+   * INTERNAL API
+   */
+  @InternalApi
   private[akka] object IdlePassivationStrategy {
     def apply(settings: PassivationStrategySettings.IdleSettings): IdlePassivationStrategy =
       IdlePassivationStrategy(settings.timeout, settings.interval.getOrElse(settings.timeout / 2))
   }
 
+  /**
+   * INTERNAL API
+   */
+  @InternalApi
   private[akka] case class IdlePassivationStrategy(timeout: FiniteDuration, interval: FiniteDuration)
       extends PassivationStrategy
 
+  /**
+   * INTERNAL API
+   */
+  @InternalApi
   private[akka] object LeastRecentlyUsedPassivationStrategy {
     def apply(
         settings: PassivationStrategySettings.LeastRecentlyUsedSettings,
@@ -398,15 +426,27 @@ object ClusterShardingSettings {
     }
   }
 
+  /**
+   * INTERNAL API
+   */
+  @InternalApi
   private[akka] case class LeastRecentlyUsedPassivationStrategy(
       limit: Int,
       segmented: immutable.Seq[Double],
       idle: Option[IdlePassivationStrategy])
       extends PassivationStrategy
 
+  /**
+   * INTERNAL API
+   */
+  @InternalApi
   private[akka] case class MostRecentlyUsedPassivationStrategy(limit: Int, idle: Option[IdlePassivationStrategy])
       extends PassivationStrategy
 
+  /**
+   * INTERNAL API
+   */
+  @InternalApi
   private[akka] object LeastFrequentlyUsedPassivationStrategy {
     def apply(
         settings: PassivationStrategySettings.LeastFrequentlyUsedSettings,
@@ -415,6 +455,10 @@ object ClusterShardingSettings {
       LeastFrequentlyUsedPassivationStrategy(limit, settings.dynamicAging, idle)
   }
 
+  /**
+   * INTERNAL API
+   */
+  @InternalApi
   private[akka] case class LeastFrequentlyUsedPassivationStrategy(
       limit: Int,
       dynamicAging: Boolean,
@@ -850,6 +894,10 @@ final class ClusterShardingSettings(
   def withPassivateIdleAfter(duration: java.time.Duration): ClusterShardingSettings =
     copy(passivationStrategySettings = passivationStrategySettings.withOldIdleStrategy(duration.asScala))
 
+  /**
+   * API MAY CHANGE: Settings for passivation strategies may change after additional testing and feedback.
+   */
+  @ApiMayChange
   def withPassivationStrategy(settings: ClusterShardingSettings.PassivationStrategySettings): ClusterShardingSettings =
     copy(passivationStrategySettings = settings)
 

akka-cluster-sharding/src/main/scala/akka/cluster/sharding/internal/EntityPassivationStrategy.scala

@@ -12,6 +12,9 @@ import akka.util.{ FrequencyList, RecencyList, SegmentedRecencyList }
 import scala.collection.immutable
 import scala.concurrent.duration.FiniteDuration
 
+/**
+ * INTERNAL API
+ */
 @InternalApi
 private[akka] object EntityPassivationStrategy {
   type PassivateEntities = immutable.Seq[EntityId]
@@ -40,7 +43,7 @@ private[akka] object EntityPassivationStrategy {
 }
 
 /**
- * An entity passivation strategy, which is instantiated per active shard.
+ * INTERNAL API: An entity passivation strategy, which is instantiated per active shard.
  */
 @InternalApi
 private[akka] sealed abstract class EntityPassivationStrategy {
@@ -80,7 +83,7 @@ private[akka] sealed abstract class EntityPassivationStrategy {
 }
 
 /**
- * No-op passivation strategy for when automatic passivation is disabled.
+ * INTERNAL API: No-op passivation strategy for when automatic passivation is disabled.
  */
 @InternalApi
 private[akka] object DisabledEntityPassivationStrategy extends EntityPassivationStrategy {
@@ -93,11 +96,14 @@ private[akka] object DisabledEntityPassivationStrategy extends EntityPassivation
   override def intervalPassed(): PassivateEntities = PassivateEntities.none
 }
 
+/**
+ * INTERNAL API
+ */
 @InternalApi
 private[akka] final class IdleCheck(val timeout: FiniteDuration, val interval: FiniteDuration)
 
 /**
- * Passivates entities when they have not received a message for a specified length of time.
+ * INTERNAL API: Passivates entities when they have not received a message for a specified length of time.
  * @param idleCheck passivate idle entities after the given timeout, checking every interval
  */
 @InternalApi
@@ -122,7 +128,7 @@ private[akka] final class IdleEntityPassivationStrategy(idleCheck: IdleCheck) ex
 }
 
 /**
- * Passivate the least recently used entities when the number of active entities in a shard region
+ * INTERNAL API: Passivate the least recently used entities when the number of active entities in a shard region
  * reaches a limit. The per-region limit is divided evenly among the active shards in a region.
  * @param perRegionLimit active entity capacity for a shard region
  * @param idleCheck optionally passivate idle entities after the given timeout, checking every interval
@@ -161,6 +167,8 @@ private[akka] final class LeastRecentlyUsedEntityPassivationStrategy(perRegionLi
 }
 
 /**
+ * INTERNAL API
+ *
  * Passivate the least recently used entities when the number of active entities in a shard region
  * reaches a limit. The per-region limit is divided evenly among the active shards in a region.
  * Active entities are tracked in multiple recency lists, where entities are promoted to higher-level
@@ -210,6 +218,8 @@ private[akka] final class SegmentedLeastRecentlyUsedEntityPassivationStrategy(
 }
 
 /**
+ * INTERNAL API
+ *
  * Passivate the most recently used entities when the number of active entities in a shard region
  * reaches a limit. The per-region limit is divided evenly among the active shards in a region.
  * @param perRegionLimit active entity capacity for a shard region
@@ -249,6 +259,8 @@ private[akka] final class MostRecentlyUsedEntityPassivationStrategy(perRegionLim
 }
 
 /**
+ * INTERNAL API
+ *
  * Passivate the least frequently used entities when the number of active entities in a shard region
  * reaches a limit. The per-region limit is divided evenly among the active shards in a region.
  * @param perRegionLimit active entity capacity for a shard region

akka-docs/src/main/paradox/typed/cluster-sharding.md

@@ -294,6 +294,16 @@ and this is the current default strategy to maintain compatibility with earlier
 a [passivation strategy with an active entity limit](#active-entity-limits) and a pre-configured default strategy is
 provided. Active entity limits and idle entity timeouts can also be used together.
 
+@@@ note
+
+The automatic passivation strategies, except [passivate idle entities](#idle-entity-passivation)
+are marked as @ref:[may change](../common/may-change.md) in the sense of being the subject of final development.
+This means that the configuration or semantics can change without warning or deprecation period. The passivation
+strategies can be used in production, but we reserve the right to adjust the configuration after additional
+testing and feedback.
+
+@@@
+
 Automatic passivation can be disabled by setting `akka.cluster.sharding.passivation.strategy = none`. It is disabled
 automatically if @ref:[Remembering Entities](#remembering-entities) is enabled.