You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pekko.apache.org by he...@apache.org on 2026/07/18 09:46:29 UTC
(pekko) branch docs/3253-adjust-pool-size-semantics created (now e943017ffa)
This is an automated email from the ASF dual-hosted git repository.
He-Pin pushed a change to branch docs/3253-adjust-pool-size-semantics
in repository https://gitbox.apache.org/repos/asf/pekko.git
at e943017ffa docs: clarify pool management and resizer bounds
This branch includes the following new commits:
new e943017ffa docs: clarify pool management and resizer bounds
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@pekko.apache.org
For additional commands, e-mail: commits-help@pekko.apache.org
(pekko) 01/01: docs: clarify pool management and resizer bounds
Posted by he...@apache.org.
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: 虎鸣 <he...@alibaba-inc.com>
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: commits-unsubscribe@pekko.apache.org
For additional commands, e-mail: commits-help@pekko.apache.org