This is an automated email from the ASF dual-hosted git repository. He-Pin pushed a commit to branch docs/3253-adjust-pool-size-semantics in repository https://gitbox.apache.org/repos/asf/pekko.git
commit e943017ffa53535e6e2f7b3c1939a6e06da9b535 Author: 虎鸣 <[email protected]> AuthorDate: Sat Jul 18 17:45:59 2026 +0800 docs: clarify pool management and resizer bounds Motivation: AdjustPoolSize is a direct management operation, but resizer documentation described lower and upper bounds as values the router should ever have. Modification: Clarify that nr-of-instances is initial, management operations may move a pool outside resizer bounds, and a later resize may restore the range. Document message-loss behavior when a resizable pool is reduced to zero. Result: Router management and automatic resizer responsibilities are documented consistently with the implementation. Tests: - Not run - docs only - sbt "actor / Compile / doc" "docs / paradox" - sbt +headerCheckAll checkCodeStyle - scalafmt --list --mode diff-ref=origin/main - git diff --check origin/main References: Refs #3253 --- actor/src/main/resources/reference.conf | 16 ++++++++++++---- .../main/scala/org/apache/pekko/routing/Resizer.scala | 6 ++++-- .../scala/org/apache/pekko/routing/RouterConfig.scala | 7 +++++++ docs/src/main/paradox/routing.md | 6 ++++++ 4 files changed, 29 insertions(+), 6 deletions(-) diff --git a/actor/src/main/resources/reference.conf b/actor/src/main/resources/reference.conf index 9a7cf7b62c..77ea3d117f 100644 --- a/actor/src/main/resources/reference.conf +++ b/actor/src/main/resources/reference.conf @@ -240,10 +240,14 @@ pekko { enabled = off - # The fewest number of routees the router should ever have. + # These bounds are enforced when this resizer is invoked. Router + # management messages can move the pool outside them until the + # resizer runs again. + + # The minimum pool size targeted by this resizer. lower-bound = 1 - # The most number of routees the router should ever have. + # The maximum pool size targeted by this resizer. # Must be greater than or equal to lower-bound. upper-bound = 10 @@ -289,10 +293,14 @@ pekko { enabled = off - # The fewest number of routees the router should ever have. + # These bounds are enforced when this resizer is invoked. Router + # management messages can move the pool outside them until the + # resizer runs again. + + # The minimum pool size targeted by this resizer. lower-bound = 1 - # The most number of routees the router should ever have. + # The maximum pool size targeted by this resizer. # Must be greater than or equal to lower-bound. upper-bound = 10 diff --git a/actor/src/main/scala/org/apache/pekko/routing/Resizer.scala b/actor/src/main/scala/org/apache/pekko/routing/Resizer.scala index 0addb8c6d8..3208cd099d 100644 --- a/actor/src/main/scala/org/apache/pekko/routing/Resizer.scala +++ b/actor/src/main/scala/org/apache/pekko/routing/Resizer.scala @@ -107,8 +107,10 @@ case object DefaultResizer { /** * Implementation of [[Resizer]] that adjust the [[Pool]] based on specified * thresholds. - * @param lowerBound The fewest number of routees the router should ever have. - * @param upperBound The most number of routees the router should ever have. Must be greater than or equal to `lowerBound`. + * Router management messages can move the pool outside the configured bounds + * until this resizer runs again. + * @param lowerBound The minimum pool size targeted when this resizer is invoked. + * @param upperBound The maximum pool size targeted when this resizer is invoked. Must be greater than or equal to `lowerBound`. * @param pressureThreshold Threshold to evaluate if routee is considered to be busy (under pressure). * Implementation depends on this value (default is 1). * <ul> diff --git a/actor/src/main/scala/org/apache/pekko/routing/RouterConfig.scala b/actor/src/main/scala/org/apache/pekko/routing/RouterConfig.scala index db84b801e2..2dbd45a14a 100644 --- a/actor/src/main/scala/org/apache/pekko/routing/RouterConfig.scala +++ b/actor/src/main/scala/org/apache/pekko/routing/RouterConfig.scala @@ -444,6 +444,13 @@ final case class RemoveRoutee(routee: Routee) extends RouterManagementMesssage * * Positive `change` will add that number of routees to the [[Pool]]. * Negative `change` will remove that number of routees from the [[Pool]]. + * This is a direct management operation, so `change` is not constrained by the + * pool's initial `nrOfInstances` or by bounds configured on a [[Resizer]]. + * A resizer may adjust the pool back within its bounds the next time it runs. + * + * If a resizable pool is reduced to zero routees, the ordinary message that + * triggers the next resize may be lost before new routees are added. + * * Routees are stopped by sending a [[pekko.actor.PoisonPill]] to the routee. * Precautions are taken reduce the risk of dropping messages that are concurrently * being routed to the removed routee, but it is not guaranteed that messages are not diff --git a/docs/src/main/paradox/routing.md b/docs/src/main/paradox/routing.md index b421780094..111983156b 100644 --- a/docs/src/main/paradox/routing.md +++ b/docs/src/main/paradox/routing.md @@ -799,6 +799,12 @@ an ordinary message you are not guaranteed that the routees have been changed wh is routed. If you need to know when the change has been applied you can send `AddRoutee` followed by `GetRoutees` and when you receive the `Routees` reply you know that the preceding change has been applied. +Routee-changing management messages directly change the routees. The `nr-of-instances` setting only defines the initial +pool size, and changes made by management messages are not constrained by configured resizer bounds. A resizer may +adjust the pool back within its bounds the next time it runs. If management messages reduce a resizable pool to zero +routees, ordinary messages are lost until the resizer adds routees. A message that triggers a resize is routed without +waiting for that resize to complete, so it may be lost if no routees have been added yet. + <a id="resizable-routers"></a> ## Dynamically Resizable Pool --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
