package routing
- Alphabetic
- Public
- Protected
Type Members
- final case class ActorRefRoutee(ref: ActorRef) extends Routee with Product with Serializable
Routee that sends the messages to an pekko.actor.ActorRef.
- final case class ActorSelectionRoutee(selection: ActorSelection) extends Routee with Product with Serializable
Routee that sends the messages to an pekko.actor.ActorSelection.
- final case class AddRoutee(routee: Routee) extends RouterManagementMesssage with Product with Serializable
Add a routee by sending this message to the router.
Add a routee by sending this message to the router. It may be handled after other messages.
- Annotations
- @SerialVersionUID()
- final case class AdjustPoolSize(change: Int) extends RouterManagementMesssage with Product with Serializable
Increase or decrease the number of routees in a Pool.
Increase or decrease the number of routees in a Pool. It may be handled after other messages.
Positive
change
will add that number of routees to the Pool. Negativechange
will remove that number of routees from the Pool. 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 lost.- Annotations
- @SerialVersionUID()
- final case class BalancingPool(nrOfInstances: Int, supervisorStrategy: SupervisorStrategy = Pool.defaultSupervisorStrategy, routerDispatcher: String = Dispatchers.DefaultDispatcherId) extends Pool with Product with Serializable
A router pool that will try to redistribute work from busy routees to idle routees.
A router pool that will try to redistribute work from busy routees to idle routees. All routees share the same mailbox.
Although the technique used in this implementation is commonly known as "work stealing", the actual implementation is probably best described as "work donating" because the actor of which work is being stolen takes the initiative.
The configuration parameter trumps the constructor arguments. This means that if you provide
nrOfInstances
during instantiation they will be ignored if the router is defined in the configuration file for the actor being used.Supervision Setup
Any routees that are created by a router will be created as the router's children. The router is therefore also the children's supervisor.
The supervision strategy of the router actor can be configured with #withSupervisorStrategy. If no strategy is provided, routers default to a strategy of “always escalate”. This means that errors are passed up to the router's supervisor for handling.
The router's supervisor will treat the error as an error with the router itself. Therefore a directive to stop or restart will cause the router itself to stop or restart. The router, in turn, will cause its children to stop and restart.
- nrOfInstances
initial number of routees in the pool
- supervisorStrategy
strategy for supervising the routees, see 'Supervision Setup'
- routerDispatcher
dispatcher to use for the router head actor, which handles supervision, death watch and router management messages
- Annotations
- @SerialVersionUID()
- final case class Broadcast(message: Any) extends RouterEnvelope with Product with Serializable
Used to broadcast a message to all routees in a router; only the contained message will be forwarded, i.e.
Used to broadcast a message to all routees in a router; only the contained message will be forwarded, i.e. the
Broadcast(...)
envelope will be stripped off.- Annotations
- @SerialVersionUID()
- final case class BroadcastGroup(paths: Iterable[String], routerDispatcher: String = Dispatchers.DefaultDispatcherId) extends Group with Product with Serializable
A router group that broadcasts a message to all its routees.
A router group that broadcasts a message to all its routees.
The configuration parameter trumps the constructor arguments. This means that if you provide
paths
during instantiation they will be ignored if the router is defined in the configuration file for the actor being used.- paths
string representation of the actor paths of the routees, messages are sent with pekko.actor.ActorSelection to these paths
- routerDispatcher
dispatcher to use for the router head actor, which handles router management messages
- Annotations
- @SerialVersionUID()
- final case class BroadcastPool(nrOfInstances: Int, resizer: Option[Resizer] = None, supervisorStrategy: SupervisorStrategy = Pool.defaultSupervisorStrategy, routerDispatcher: String = Dispatchers.DefaultDispatcherId, usePoolDispatcher: Boolean = false) extends Pool with PoolOverrideUnsetConfig[BroadcastPool] with Product with Serializable
A router pool that broadcasts a message to all its routees.
A router pool that broadcasts a message to all its routees.
The configuration parameter trumps the constructor arguments. This means that if you provide
nrOfInstances
during instantiation they will be ignored if the router is defined in the configuration file for the actor being used.Supervision Setup
Any routees that are created by a router will be created as the router's children. The router is therefore also the children's supervisor.
The supervision strategy of the router actor can be configured with #withSupervisorStrategy. If no strategy is provided, routers default to a strategy of “always escalate”. This means that errors are passed up to the router's supervisor for handling.
The router's supervisor will treat the error as an error with the router itself. Therefore a directive to stop or restart will cause the router itself to stop or restart. The router, in turn, will cause its children to stop and restart.
- nrOfInstances
initial number of routees in the pool
- resizer
optional resizer that dynamically adjust the pool size
- supervisorStrategy
strategy for supervising the routees, see 'Supervision Setup'
- routerDispatcher
dispatcher to use for the router head actor, which handles supervision, death watch and router management messages
- Annotations
- @SerialVersionUID()
- final class BroadcastRoutingLogic extends RoutingLogic
Broadcasts a message to all its routees.
Broadcasts a message to all its routees.
- Annotations
- @nowarn() @SerialVersionUID()
- class ConsistentHash[T] extends AnyRef
Consistent Hashing node ring implementation.
Consistent Hashing node ring implementation.
A good explanation of Consistent Hashing: https://tom-e-white.com/2007/11/consistent-hashing.html
Note that toString of the ring nodes are used for the node hash, i.e. make sure it is different for different nodes.
- final case class ConsistentHashingGroup(paths: Iterable[String], virtualNodesFactor: Int = 0, hashMapping: ConsistentHashMapping = ConsistentHashingRouter.emptyConsistentHashMapping, routerDispatcher: String = Dispatchers.DefaultDispatcherId) extends Group with Product with Serializable
A router group that uses consistent hashing to select a routee based on the sent message.
A router group that uses consistent hashing to select a routee based on the sent message. The selection is described in pekko.routing.ConsistentHashingRoutingLogic.
The configuration parameter trumps the constructor arguments. This means that if you provide
paths
during instantiation they will be ignored if the router is defined in the configuration file for the actor being used.- paths
string representation of the actor paths of the routees, messages are sent with pekko.actor.ActorSelection to these paths
- virtualNodesFactor
number of virtual nodes per node, used in pekko.routing.ConsistentHash
- hashMapping
partial function from message to the data to use for the consistent hash key
- routerDispatcher
dispatcher to use for the router head actor, which handles router management messages
- Annotations
- @SerialVersionUID()
- final case class ConsistentHashingPool(nrOfInstances: Int, resizer: Option[Resizer] = None, virtualNodesFactor: Int = 0, hashMapping: ConsistentHashMapping = ConsistentHashingRouter.emptyConsistentHashMapping, supervisorStrategy: SupervisorStrategy = Pool.defaultSupervisorStrategy, routerDispatcher: String = Dispatchers.DefaultDispatcherId, usePoolDispatcher: Boolean = false) extends Pool with PoolOverrideUnsetConfig[ConsistentHashingPool] with Product with Serializable
A router pool that uses consistent hashing to select a routee based on the sent message.
A router pool that uses consistent hashing to select a routee based on the sent message. The selection is described in pekko.routing.ConsistentHashingRoutingLogic.
The configuration parameter trumps the constructor arguments. This means that if you provide
nrOfInstances
during instantiation they will be ignored if the router is defined in the configuration file for the actor being used.Supervision Setup
Any routees that are created by a router will be created as the router's children. The router is therefore also the children's supervisor.
The supervision strategy of the router actor can be configured with #withSupervisorStrategy. If no strategy is provided, routers default to a strategy of “always escalate”. This means that errors are passed up to the router's supervisor for handling.
The router's supervisor will treat the error as an error with the router itself. Therefore a directive to stop or restart will cause the router itself to stop or restart. The router, in turn, will cause its children to stop and restart.
- nrOfInstances
initial number of routees in the pool
- resizer
optional resizer that dynamically adjust the pool size
- virtualNodesFactor
number of virtual nodes per node, used in pekko.routing.ConsistentHash
- hashMapping
partial function from message to the data to use for the consistent hash key
- supervisorStrategy
strategy for supervising the routees, see 'Supervision Setup'
- routerDispatcher
dispatcher to use for the router head actor, which handles supervision, death watch and router management messages
- Annotations
- @SerialVersionUID()
- final case class ConsistentHashingRoutingLogic(system: ActorSystem, virtualNodesFactor: Int = 0, hashMapping: ConsistentHashMapping = ConsistentHashingRouter.emptyConsistentHashMapping) extends RoutingLogic with Product with Serializable
Uses consistent hashing to select a routee based on the sent message.
Uses consistent hashing to select a routee based on the sent message.
There is 3 ways to define what data to use for the consistent hash key.
1. You can define
hashMapping
/withHashMapper
of the router to map incoming messages to their consistent hash key. This makes the decision transparent for the sender.2. The messages may implement pekko.routing.ConsistentHashingRouter.ConsistentHashable. The key is part of the message and it's convenient to define it together with the message definition.
3. The messages can be wrapped in a pekko.routing.ConsistentHashingRouter.ConsistentHashableEnvelope to define what data to use for the consistent hash key. The sender knows the key to use.
These ways to define the consistent hash key can be use together and at the same time for one router. The
hashMapping
is tried first.- system
the actor system hosting this router
- virtualNodesFactor
number of virtual nodes per node, used in pekko.routing.ConsistentHash
- hashMapping
partial function from message to the data to use for the consistent hash key
- Annotations
- @SerialVersionUID()
- abstract class CustomRouterConfig extends RouterConfig
If a custom router implementation is not a Group nor a Pool it may extend this base class.
- final case class Deafen(listener: ActorRef) extends ListenerMessage with Product with Serializable
- case class DefaultOptimalSizeExploringResizer(lowerBound: PoolSize = 1, upperBound: PoolSize = 30, chanceOfScalingDownWhenFull: Double = 0.2, actionInterval: Duration = 5.seconds, numOfAdjacentSizesToConsiderDuringOptimization: Int = 16, exploreStepSize: Double = 0.1, downsizeRatio: Double = 0.8, downsizeAfterUnderutilizedFor: Duration = 72.hours, explorationProbability: Double = 0.4, weightOfLatestMetric: Double = 0.5) extends OptimalSizeExploringResizer with Product with Serializable
This resizer resizes the pool to an optimal size that provides the most message throughput.
This resizer resizes the pool to an optimal size that provides the most message throughput.
This resizer works best when you expect the pool size to performance function to be a convex function.
For example, when you have a CPU bound tasks, the optimal size is bound to the number of CPU cores. When your task is IO bound, the optimal size is bound to optimal number of concurrent connections to that IO service - e.g. a 4 node elastic search cluster may handle 4-8 concurrent requests at optimal speed.
It achieves this by keeping track of message throughput at each pool size and performing the following three resizing operations (one at a time) periodically:
* Downsize if it hasn't seen all routees ever fully utilized for a period of time. * Explore to a random nearby pool size to try and collect throughput metrics. * Optimize to a nearby pool size with a better (than any other nearby sizes) throughput metrics.
When the pool is fully-utilized (i.e. all routees are busy), it randomly choose between exploring and optimizing. When the pool has not been fully-utilized for a period of time, it will downsize the pool to the last seen max utilization multiplied by a configurable ratio.
By constantly exploring and optimizing, the resizer will eventually walk to the optimal size and remain nearby. When the optimal size changes it will start walking towards the new one.
It keeps a performance log so it's stateful as well as having a larger memory footprint than the default Resizer. The memory usage is O(n) where n is the number of sizes you allow, i.e. upperBound - lowerBound.
For documentation about the parameters, see the reference.conf - pekko.actor.deployment.default.optimal-size-exploring-resizer
- Annotations
- @SerialVersionUID()
- case class DefaultResizer(lowerBound: Int = 1, upperBound: Int = 10, pressureThreshold: Int = 1, rampupRate: Double = 0.2, backoffThreshold: Double = 0.3, backoffRate: Double = 0.1, messagesPerResize: Int = 10) extends Resizer with Product with Serializable
Implementation of Resizer that adjust the Pool based on specified thresholds.
- lowerBound
The fewest number of routees the router should ever have.
- upperBound
The most number of routees the router should ever have. Must be greater than or equal to
lowerBound
.- pressureThreshold
Threshold to evaluate if routee is considered to be busy (under pressure). Implementation depends on this value (default is 1).
- 0: number of routees currently processing a message.
- 1: number of routees currently processing a message has some messages in mailbox.
- > 1: number of routees with at least the configured
pressureThreshold
messages in their mailbox. Note that estimating mailbox size of default UnboundedMailbox is O(N) operation.
- rampupRate
Percentage to increase capacity whenever all routees are busy. For example, 0.2 would increase 20% (rounded up), i.e. if current capacity is 6 it will request an increase of 2 more routees.
- backoffThreshold
Minimum fraction of busy routees before backing off. For example, if this is 0.3, then we'll remove some routees only when less than 30% of routees are busy, i.e. if current capacity is 10 and 3 are busy then the capacity is unchanged, but if 2 or less are busy the capacity is decreased. Use 0.0 or negative to avoid removal of routees.
- backoffRate
Fraction of routees to be removed when the resizer reaches the backoffThreshold. For example, 0.1 would decrease 10% (rounded up), i.e. if current capacity is 9 it will request an decrease of 1 routee.
- messagesPerResize
Number of messages between resize operation. Use 1 to resize before each message.
- Annotations
- @SerialVersionUID()
- class FromConfig extends Pool
Java API: Wraps a pekko.actor.Props to mark the actor as externally configurable to be used with a router.
Java API: Wraps a pekko.actor.Props to mark the actor as externally configurable to be used with a router. If a pekko.actor.Props is not wrapped with FromConfig then the actor will ignore the router part of the deployment section in the configuration.
This can be used when the dispatcher to be used for the head Router needs to be configured (defaults to default-dispatcher).
- Annotations
- @SerialVersionUID()
- abstract class GetRoutees extends RouterManagementMesssage
Sending this message to a router will make it send back its currently used routees.
Sending this message to a router will make it send back its currently used routees. A Routees message is sent asynchronously to the "requester" containing information about what routees the router is routing over.
- Annotations
- @nowarn() @SerialVersionUID()
- trait Group extends RouterConfig
RouterConfig
for router actor with routee actors that are created external to the router and the router sends messages to the specified path using actor selection, without watching for termination. - abstract class GroupBase extends Group
Java API: Base class for custom router Group
- final case class Listen(listener: ActorRef) extends ListenerMessage with Product with Serializable
- sealed trait ListenerMessage extends AnyRef
- trait Listeners extends AnyRef
Listeners is a generic trait to implement listening capability on an Actor.
Listeners is a generic trait to implement listening capability on an Actor.
Use the
gossip(msg)
method to have it sent to the listeners.Send
Listen(self)
to start listening.Send
Deafen(self)
to stop listening.Send
WithListeners(fun)
to traverse the current listeners. - abstract class NoRouter extends RouterConfig
Routing configuration that indicates no routing; this is also the default value which hence overrides the merge strategy in order to accept values from lower-precedence sources.
Routing configuration that indicates no routing; this is also the default value which hence overrides the merge strategy in order to accept values from lower-precedence sources. The decision whether or not to create a router is taken in the LocalActorRefProvider based on Props.
- Annotations
- @SerialVersionUID()
- trait OptimalSizeExploringResizer extends Resizer
- trait Pool extends RouterConfig
RouterConfig
for router actor that creates routees as child actors and removes them from the router if they terminate. - abstract class PoolBase extends Pool
Java API: Base class for custom router Pool
- final case class RandomGroup(paths: Iterable[String], routerDispatcher: String = Dispatchers.DefaultDispatcherId) extends Group with Product with Serializable
A router group that randomly selects one of the target routees to send a message to.
A router group that randomly selects one of the target routees to send a message to.
The configuration parameter trumps the constructor arguments. This means that if you provide
paths
during instantiation they will be ignored if the router is defined in the configuration file for the actor being used.- paths
string representation of the actor paths of the routees, messages are sent with pekko.actor.ActorSelection to these paths
- routerDispatcher
dispatcher to use for the router head actor, which handles router management messages
- Annotations
- @SerialVersionUID()
- final case class RandomPool(nrOfInstances: Int, resizer: Option[Resizer] = None, supervisorStrategy: SupervisorStrategy = Pool.defaultSupervisorStrategy, routerDispatcher: String = Dispatchers.DefaultDispatcherId, usePoolDispatcher: Boolean = false) extends Pool with PoolOverrideUnsetConfig[RandomPool] with Product with Serializable
A router pool that randomly selects one of the target routees to send a message to.
A router pool that randomly selects one of the target routees to send a message to.
The configuration parameter trumps the constructor arguments. This means that if you provide
nrOfInstances
during instantiation they will be ignored if the router is defined in the configuration file for the actor being used.Supervision Setup
Any routees that are created by a router will be created as the router's children. The router is therefore also the children's supervisor.
The supervision strategy of the router actor can be configured with #withSupervisorStrategy. If no strategy is provided, routers default to a strategy of “always escalate”. This means that errors are passed up to the router's supervisor for handling.
The router's supervisor will treat the error as an error with the router itself. Therefore a directive to stop or restart will cause the router itself to stop or restart. The router, in turn, will cause its children to stop and restart.
- nrOfInstances
initial number of routees in the pool
- resizer
optional resizer that dynamically adjust the pool size
- supervisorStrategy
strategy for supervising the routees, see 'Supervision Setup'
- routerDispatcher
dispatcher to use for the router head actor, which handles supervision, death watch and router management messages
- Annotations
- @SerialVersionUID()
- final class RandomRoutingLogic extends RoutingLogic
Randomly selects one of the target routees to send a message to
Randomly selects one of the target routees to send a message to
- Annotations
- @nowarn() @SerialVersionUID()
- final case class RemoveRoutee(routee: Routee) extends RouterManagementMesssage with Product with Serializable
Remove a specific routee by sending this message to the router.
Remove a specific routee by sending this message to the router. It may be handled after other messages.
For a pool, with child routees, the routee is 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 there are no guarantees.
- Annotations
- @SerialVersionUID()
- trait Resizer extends AnyRef
Pool routers with dynamically resizable number of routees are implemented by providing a Resizer implementation in the pekko.routing.Pool configuration.
- class ResizerInitializationException extends PekkoException
- Annotations
- @SerialVersionUID()
- final case class RoundRobinGroup(paths: Iterable[String], routerDispatcher: String = Dispatchers.DefaultDispatcherId) extends Group with Product with Serializable
A router group that uses round-robin to select a routee.
A router group that uses round-robin to select a routee. For concurrent calls, round robin is just a best effort.
The configuration parameter trumps the constructor arguments. This means that if you provide
paths
during instantiation they will be ignored if the router is defined in the configuration file for the actor being used.- paths
string representation of the actor paths of the routees, messages are sent with pekko.actor.ActorSelection to these paths
- routerDispatcher
dispatcher to use for the router head actor, which handles router management messages
- Annotations
- @SerialVersionUID()
- final case class RoundRobinPool(nrOfInstances: Int, resizer: Option[Resizer] = None, supervisorStrategy: SupervisorStrategy = Pool.defaultSupervisorStrategy, routerDispatcher: String = Dispatchers.DefaultDispatcherId, usePoolDispatcher: Boolean = false) extends Pool with PoolOverrideUnsetConfig[RoundRobinPool] with Product with Serializable
A router pool that uses round-robin to select a routee.
A router pool that uses round-robin to select a routee. For concurrent calls, round robin is just a best effort.
The configuration parameter trumps the constructor arguments. This means that if you provide
nrOfInstances
during instantiation they will be ignored if the router is defined in the configuration file for the actor being used.Supervision Setup
Any routees that are created by a router will be created as the router's children. The router is therefore also the children's supervisor.
The supervision strategy of the router actor can be configured with #withSupervisorStrategy. If no strategy is provided, routers default to a strategy of “always escalate”. This means that errors are passed up to the router's supervisor for handling.
The router's supervisor will treat the error as an error with the router itself. Therefore a directive to stop or restart will cause the router itself to stop or restart. The router, in turn, will cause its children to stop and restart.
- nrOfInstances
initial number of routees in the pool
- resizer
optional resizer that dynamically adjust the pool size
- supervisorStrategy
strategy for supervising the routees, see 'Supervision Setup'
- routerDispatcher
dispatcher to use for the router head actor, which handles supervision, death watch and router management messages
- Annotations
- @SerialVersionUID()
- final class RoundRobinRoutingLogic extends RoutingLogic
Uses round-robin to select a routee.
Uses round-robin to select a routee. For concurrent calls, round robin is just a best effort.
- Annotations
- @nowarn() @SerialVersionUID()
- trait Routee extends AnyRef
Abstraction of a destination for messages routed via a Router.
- final case class Routees(routees: IndexedSeq[Routee]) extends Product with Serializable
Message used to carry information about what routees the router is currently using.
Message used to carry information about what routees the router is currently using.
- Annotations
- @SerialVersionUID()
- final case class Router(logic: RoutingLogic, routees: IndexedSeq[Routee] = Vector.empty) extends Product with Serializable
For each message that is sent through the router via the #route method the RoutingLogic decides to which Routee to send the message.
For each message that is sent through the router via the #route method the RoutingLogic decides to which Routee to send the message. The Routee itself knows how to perform the actual sending. Normally the RoutingLogic picks one of the contained
routees
, but that is up to the implementation of the RoutingLogic.A
Router
is immutable and the RoutingLogic must be thread safe. - trait RouterConfig extends Serializable
This trait represents a router factory: it produces the actual router actor and creates the routing table (a function which determines the recipients for each message which is to be dispatched).
This trait represents a router factory: it produces the actual router actor and creates the routing table (a function which determines the recipients for each message which is to be dispatched). The resulting RoutedActorRef optimizes the sending of the message so that it does NOT go through the router’s mailbox unless the route returns an empty recipient set.
Caution: This means that the route function is evaluated concurrently without protection by the RoutedActorRef: either provide a reentrant (i.e. pure) implementation or do the locking yourself!
Caution: Please note that the pekko.routing.Router which needs to be returned by
createActor()
should not send a message to itself in its constructor orpreStart()
or publish its self reference from there: if someone tries sending a message to that reference before the constructor of RoutedActorRef has returned, there will be aNullPointerException
!- Annotations
- @nowarn() @SerialVersionUID()
- trait RouterEnvelope extends WrappedMessage
Only the contained message will be forwarded to the destination, i.e.
Only the contained message will be forwarded to the destination, i.e. the envelope will be stripped off.
- trait RoutingLogic extends NoSerializationVerificationNeeded
The interface of the routing logic that is used in a Router to select destination routed messages.
The interface of the routing logic that is used in a Router to select destination routed messages.
The implementation must be thread safe.
- final case class ScatterGatherFirstCompletedGroup(paths: Iterable[String], within: FiniteDuration, routerDispatcher: String = Dispatchers.DefaultDispatcherId) extends Group with Product with Serializable
A router group that broadcasts the message to all routees, and replies with the first response.
A router group that broadcasts the message to all routees, and replies with the first response.
The configuration parameter trumps the constructor arguments. This means that if you provide
paths
during instantiation they will be ignored if the router is defined in the configuration file for the actor being used.- paths
string representation of the actor paths of the routees, messages are sent with pekko.actor.ActorSelection to these paths
- within
expecting at least one reply within this duration, otherwise it will reply with pekko.pattern.AskTimeoutException in a pekko.actor.Status.Failure
- routerDispatcher
dispatcher to use for the router head actor, which handles router management messages
- Annotations
- @SerialVersionUID()
- final case class ScatterGatherFirstCompletedPool(nrOfInstances: Int, resizer: Option[Resizer] = None, within: FiniteDuration, supervisorStrategy: SupervisorStrategy = Pool.defaultSupervisorStrategy, routerDispatcher: String = Dispatchers.DefaultDispatcherId, usePoolDispatcher: Boolean = false) extends Pool with PoolOverrideUnsetConfig[ScatterGatherFirstCompletedPool] with Product with Serializable
A router pool that broadcasts the message to all routees, and replies with the first response.
A router pool that broadcasts the message to all routees, and replies with the first response.
The configuration parameter trumps the constructor arguments. This means that if you provide
nrOfInstances
during instantiation they will be ignored if the router is defined in the configuration file for the actor being used.Supervision Setup
Any routees that are created by a router will be created as the router's children. The router is therefore also the children's supervisor.
The supervision strategy of the router actor can be configured with #withSupervisorStrategy. If no strategy is provided, routers default to a strategy of “always escalate”. This means that errors are passed up to the router's supervisor for handling.
The router's supervisor will treat the error as an error with the router itself. Therefore a directive to stop or restart will cause the router itself to stop or restart. The router, in turn, will cause its children to stop and restart.
- nrOfInstances
initial number of routees in the pool
- resizer
optional resizer that dynamically adjust the pool size
- within
expecting at least one reply within this duration, otherwise it will reply with pekko.pattern.AskTimeoutException in a pekko.actor.Status.Failure
- supervisorStrategy
strategy for supervising the routees, see 'Supervision Setup'
- routerDispatcher
dispatcher to use for the router head actor, which handles supervision, death watch and router management messages
- Annotations
- @SerialVersionUID()
- final case class ScatterGatherFirstCompletedRoutingLogic(within: FiniteDuration) extends RoutingLogic with Product with Serializable
Broadcasts the message to all routees, and replies with the first response.
Broadcasts the message to all routees, and replies with the first response.
- within
expecting at least one reply within this duration, otherwise it will reply with pekko.pattern.AskTimeoutException in a pekko.actor.Status.Failure
- Annotations
- @SerialVersionUID()
- final case class SeveralRoutees(routees: IndexedSeq[Routee]) extends Routee with Product with Serializable
Routee that sends each message to all
routees
. - final case class SmallestMailboxPool(nrOfInstances: Int, resizer: Option[Resizer] = None, supervisorStrategy: SupervisorStrategy = Pool.defaultSupervisorStrategy, routerDispatcher: String = Dispatchers.DefaultDispatcherId, usePoolDispatcher: Boolean = false) extends Pool with PoolOverrideUnsetConfig[SmallestMailboxPool] with Product with Serializable
A router pool that tries to send to the non-suspended routee with fewest messages in mailbox.
A router pool that tries to send to the non-suspended routee with fewest messages in mailbox. The selection is done in this order:
- pick any idle routee (not processing message) with empty mailbox
- pick any routee with empty mailbox
- pick routee with fewest pending messages in mailbox
- pick any remote routee, remote actors are consider lowest priority, since their mailbox size is unknown
The configuration parameter trumps the constructor arguments. This means that if you provide
nrOfInstances
during instantiation they will be ignored if the router is defined in the configuration file for the actor being used.Supervision Setup
Any routees that are created by a router will be created as the router's children. The router is therefore also the children's supervisor.
The supervision strategy of the router actor can be configured with #withSupervisorStrategy. If no strategy is provided, routers default to a strategy of “always escalate”. This means that errors are passed up to the router's supervisor for handling.
The router's supervisor will treat the error as an error with the router itself. Therefore a directive to stop or restart will cause the router itself to stop or restart. The router, in turn, will cause its children to stop and restart.
- nrOfInstances
initial number of routees in the pool
- resizer
optional resizer that dynamically adjust the pool size
- supervisorStrategy
strategy for supervising the routees, see 'Supervision Setup'
- routerDispatcher
dispatcher to use for the router head actor, which handles supervision, death watch and router management messages
- Annotations
- @nowarn() @SerialVersionUID()
- class SmallestMailboxRoutingLogic extends RoutingLogic
Tries to send to the non-suspended routee with fewest messages in mailbox.
Tries to send to the non-suspended routee with fewest messages in mailbox. The selection is done in this order:
- pick any idle routee (not processing message) with empty mailbox
- pick any routee with empty mailbox
- pick routee with fewest pending messages in mailbox
- pick any remote routee, remote actors are consider lowest priority, since their mailbox size is unknown
- Annotations
- @nowarn() @SerialVersionUID()
- final case class TailChoppingGroup(paths: Iterable[String], within: FiniteDuration, interval: FiniteDuration, routerDispatcher: String = Dispatchers.DefaultDispatcherId) extends Group with Product with Serializable
A router group with retry logic, intended for cases where a return message is expected in response to a message sent to the routee.
A router group with retry logic, intended for cases where a return message is expected in response to a message sent to the routee. As each message is sent to the routing group, the routees are randomly ordered. The message is sent to the first routee. If no response is received before the
interval
has passed, the same message is sent to the next routee. This process repeats until either a response is received from some routee, the routees in the group are exhausted, or thewithin
duration has passed since the first send. If no routee sends a response in time, a pekko.actor.Status.Failure wrapping a pekko.pattern.AskTimeoutException is sent to the sender.Refer to pekko.routing.TailChoppingRoutingLogic for comments regarding the goal of this routing algorithm.
The configuration parameter trumps the constructor arguments. This means that if you provide
paths
during instantiation they will be ignored if the router is defined in the configuration file for the actor being used.- paths
string representation of the actor paths of the routees, messages are sent with pekko.actor.ActorSelection to these paths
- within
expecting at least one reply within this duration, otherwise it will reply with pekko.pattern.AskTimeoutException in a pekko.actor.Status.Failure
- interval
duration after which the message will be sent to the next routee
- routerDispatcher
dispatcher to use for the router head actor, which handles router management messages
- final case class TailChoppingPool(nrOfInstances: Int, resizer: Option[Resizer] = None, within: FiniteDuration, interval: FiniteDuration, supervisorStrategy: SupervisorStrategy = Pool.defaultSupervisorStrategy, routerDispatcher: String = Dispatchers.DefaultDispatcherId, usePoolDispatcher: Boolean = false) extends Pool with PoolOverrideUnsetConfig[TailChoppingPool] with Product with Serializable
A router pool with retry logic, intended for cases where a return message is expected in response to a message sent to the routee.
A router pool with retry logic, intended for cases where a return message is expected in response to a message sent to the routee. As each message is sent to the routing pool, the routees are randomly ordered. The message is sent to the first routee. If no response is received before the
interval
has passed, the same message is sent to the next routee. This process repeats until either a response is received from some routee, the routees in the pool are exhausted, or thewithin
duration has passed since the first send. If no routee sends a response in time, a pekko.actor.Status.Failure wrapping a pekko.pattern.AskTimeoutException is sent to the sender.Refer to pekko.routing.TailChoppingRoutingLogic for comments regarding the goal of this routing algorithm.
The configuration parameter trumps the constructor arguments. This means that if you provide
nrOfInstances
during instantiation they will be ignored if the router is defined in the configuration file for the actor being used.Supervision Setup
Any routees that are created by a router will be created as the router's children. The router is therefore also the children's supervisor.
The supervision strategy of the router actor can be configured with #withSupervisorStrategy. If no strategy is provided, routers default to a strategy of “always escalate”. This means that errors are passed up to the router's supervisor for handling.
The router's supervisor will treat the error as an error with the router itself. Therefore a directive to stop or restart will cause the router itself to stop or restart. The router, in turn, will cause its children to stop and restart.
- nrOfInstances
initial number of routees in the pool
- resizer
optional resizer that dynamically adjust the pool size
- within
expecting at least one reply within this duration, otherwise it will reply with pekko.pattern.AskTimeoutException in a pekko.actor.Status.Failure
- interval
duration after which the message will be sent to the next routee
- supervisorStrategy
strategy for supervising the routees, see 'Supervision Setup'
- routerDispatcher
dispatcher to use for the router head actor, which handles supervision, death watch and router management messages
- Annotations
- @SerialVersionUID()
- final case class TailChoppingRoutingLogic(scheduler: Scheduler, within: FiniteDuration, interval: FiniteDuration, context: ExecutionContext) extends RoutingLogic with Product with Serializable
As each message is sent to the router, the routees are randomly ordered.
As each message is sent to the router, the routees are randomly ordered. The message is sent to the first routee. If no response is received before the
interval
has passed, the same message is sent to the next routee. This process repeats until either a response is received from some routee, the routees in the pool are exhausted, or thewithin
duration has passed since the first send. If no routee sends a response in time, a pekko.actor.Status.Failure wrapping a pekko.pattern.AskTimeoutException is sent to the sender.The goal of this routing algorithm is to decrease tail latencies ("chop off the tail latency") in situations where multiple routees can perform the same piece of work, and where a routee may occasionally respond more slowly than expected. In this case, sending the same work request (also known as a "backup request") to another actor results in decreased response time - because it's less probable that multiple actors are under heavy load simultaneously. This technique is explained in depth in Jeff Dean's presentation on Achieving Rapid Response Times in Large Online Services.
- scheduler
schedules sending messages to routees
- within
expecting at least one reply within this duration, otherwise it will reply with pekko.pattern.AskTimeoutException in a pekko.actor.Status.Failure
- interval
duration after which the message will be sent to the next routee
- context
execution context used by scheduler
- Annotations
- @SerialVersionUID()
- final case class WithListeners(f: (ActorRef) => Unit) extends ListenerMessage with Product with Serializable
Value Members
- object BroadcastRoutingLogic
- object ConsistentHash
- object ConsistentHashingRouter
- object ConsistentHashingRoutingLogic extends Serializable
- case object DefaultResizer extends Product with Serializable
- case object FromConfig extends FromConfig with Product with Serializable
Wraps a pekko.actor.Props to mark the actor as externally configurable to be used with a router.
Wraps a pekko.actor.Props to mark the actor as externally configurable to be used with a router. If a pekko.actor.Props is not wrapped with FromConfig then the actor will ignore the router part of the deployment section in the configuration.
- case object GetRoutees extends GetRoutees with Product with Serializable
- Annotations
- @SerialVersionUID()
- object MurmurHash
An object designed to generate well-distributed non-cryptographic hashes.
An object designed to generate well-distributed non-cryptographic hashes. It is designed to hash a collection of integers; along with the integers to hash, it generates two magic streams of integers to increase the distribution of repetitive input sequences. Thus, three methods need to be called at each step (to start and to incorporate a new integer) to update the values. Only one method needs to be called to finalize the hash.
- Annotations
- @ccompatUsedUntil213()
- object NoRoutee extends Routee
Routee that doesn't send the message to any routee.
Routee that doesn't send the message to any routee. The Router will send the message to
deadLetters
ifNoRoutee
is returned from RoutingLogic#select - case object NoRouter extends NoRouter with Product with Serializable
- case object OptimalSizeExploringResizer extends Product with Serializable
- object Pool extends Serializable
- object RandomRoutingLogic
- object Resizer
- object RoundRobinRoutingLogic
- object SmallestMailboxRoutingLogic