This is an automated email from the ASF dual-hosted git repository.
He-Pin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pekko.git
The following commit(s) were added to refs/heads/main by this push:
new a97eea3dca docs: clarify pool management and resizer bounds (#3363)
a97eea3dca is described below
commit a97eea3dcabd8cdffb99a8e8e37646ce2a54c38d
Author: He-Pin(kerr) <[email protected]>
AuthorDate: Sat Jul 18 21:21:50 2026 +0800
docs: clarify pool management and resizer bounds (#3363)
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]
