From 0719de035beef49209367eca4496d02a969fad14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johan=20Andr=C3=A9n?= Date: Fri, 27 Sep 2019 09:50:34 +0200 Subject: [PATCH] General concepts docs ported to typed (#27765) --- .../src/main/paradox/cluster-sharding.md | 2 +- akka-docs/src/main/paradox/fault-tolerance.md | 104 ++++++- .../src/main/paradox/general/actor-systems.md | 98 +++--- akka-docs/src/main/paradox/general/actors.md | 9 +- .../src/main/paradox/general/addressing.md | 166 +--------- .../src/main/paradox/general/configuration.md | 156 +++++----- akka-docs/src/main/paradox/general/jmm.md | 9 +- .../general/message-delivery-reliability.md | 13 +- .../src/main/paradox/general/remoting.md | 26 +- .../src/main/paradox/general/supervision.md | 283 ++---------------- .../paradox/images/actor-paths-overview.png | Bin 0 -> 164265 bytes akka-docs/src/main/paradox/index-actors.md | 1 + akka-docs/src/main/paradox/index-classic.md | 2 +- ...tilities.md => index-utilities-classic.md} | 8 +- akka-docs/src/main/paradox/persistence.md | 2 +- akka-docs/src/main/paradox/routing.md | 2 +- .../src/main/paradox/stream/stream-error.md | 3 +- .../src/main/paradox/supervision-classic.md | 157 ++++++++++ .../src/main/paradox/typed/fault-tolerance.md | 8 +- .../typed/SharedMutableStateDocTest.java | 141 +++++++++ .../src/test/java/jdocs/config/ConfigDoc.java | 28 -- .../test/java/jdocs/config/ConfigDocTest.java | 70 +++++ .../typed/SharedMutableStateDocSpec.scala | 94 ++++++ .../scala/docs/config/ConfigDocSpec.scala | 56 +++- 24 files changed, 814 insertions(+), 624 deletions(-) create mode 100644 akka-docs/src/main/paradox/images/actor-paths-overview.png rename akka-docs/src/main/paradox/{classic/index-utilities.md => index-utilities-classic.md} (68%) create mode 100644 akka-docs/src/main/paradox/supervision-classic.md create mode 100644 akka-docs/src/test/java/jdocs/actor/typed/SharedMutableStateDocTest.java delete mode 100644 akka-docs/src/test/java/jdocs/config/ConfigDoc.java create mode 100644 akka-docs/src/test/java/jdocs/config/ConfigDocTest.java create mode 100644 akka-docs/src/test/scala/docs/actor/typed/SharedMutableStateDocSpec.scala diff --git a/akka-docs/src/main/paradox/cluster-sharding.md b/akka-docs/src/main/paradox/cluster-sharding.md index 7f1aeadc70..6065e71642 100644 --- a/akka-docs/src/main/paradox/cluster-sharding.md +++ b/akka-docs/src/main/paradox/cluster-sharding.md @@ -209,7 +209,7 @@ Java Note that stopped entities will be started again when a new message is targeted to the entity. -If 'on stop' backoff supervision strategy is used, a final termination message must be set and used for passivation, see @ref:[Supervision](general/supervision.md#sharding) +If 'on stop' backoff supervision strategy is used, a final termination message must be set and used for passivation, see @ref:[Backoff supervisor and sharding](fault-tolerance.md#sharding) ## Graceful Shutdown diff --git a/akka-docs/src/main/paradox/fault-tolerance.md b/akka-docs/src/main/paradox/fault-tolerance.md index f1d4245896..a80c246d20 100644 --- a/akka-docs/src/main/paradox/fault-tolerance.md +++ b/akka-docs/src/main/paradox/fault-tolerance.md @@ -128,7 +128,7 @@ by overriding the `logFailure` method. ## Supervision of Top-Level Actors Toplevel actors means those which are created using `system.actorOf()`, and -they are children of the @ref:[User Guardian](general/supervision.md#user-guardian). There are no +they are children of the @ref:[User Guardian](supervision-classic.md#user-guardian). There are no special rules applied in this case, the guardian applies the configured strategy. @@ -230,3 +230,105 @@ Scala Java : @@snip [FaultHandlingTest.java](/akka-docs/src/test/java/jdocs/actor/FaultHandlingTest.java) { #escalate-restart } + + +## Delayed restarts for classic actors + +The supervision strategy to restart a classic actor only provides immediate restart. In some cases that will only trigger +the same failure right away and giving things a bit of time before restarting is required to actually resolve the failure. + +The `akka.pattern.BackoffSupervisor` implements the so-called +*exponential backoff supervision strategy*, starting a child actor again when it fails, each time with a growing time delay between restarts. + +This pattern is useful when the started actor fails [1] because some external resource is not available, +and we need to give it some time to start-up again. One of the prime examples when this is useful is +when a @ref:[PersistentActor](persistence.md) fails (by stopping) with a persistence failure - which indicates that +the database may be down or overloaded, in such situations it makes most sense to give it a little bit of time +to recover before the persistent actor is started. + +> [1] A failure can be indicated in two different ways; by an actor stopping or crashing. + +### Supervision strategies + +There are two basic supervision strategies available for backoff: + +* 'On failure': The supervisor will terminate and then start the supervised actor if it crashes. If the supervised actor stops normally (e.g. through `context.stop`), the supervisor will be terminated and no further attempt to start the supervised actor will be done. +* 'On stop': The supervisor will terminate and then start the supervised actor if it terminates in any way (consider this for `PersistentActor` since they stop on persistence failures instead of crashing) + +To note that this supervision strategy does not restart the actor but rather stops and starts it. Be aware of it if you +use @scala[`Stash` trait’s] @java[`AbstractActorWithStash`] in combination with the backoff supervision strategy. +The `preRestart` hook will not be executed if the supervised actor fails or stops and you will miss the opportunity +to unstash the messages. + +### Sharding +If the 'on stop' strategy is used for sharded actors a final termination message should be configured and used to terminate the actor on passivation. Otherwise the supervisor will just stop and start the actor again. + +The termination message is configured with: + +@@snip [BackoffSupervisorDocSpec.scala](/akka-docs/src/test/scala/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-sharded } + +And must be used for passivation: + +@@snip [BackoffSupervisorDocSpec.scala](/akka-docs/src/test/scala/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-sharded-passivation } + + +### Simple backoff + +The following Scala snippet shows how to create a backoff supervisor which will start the given echo actor after it has stopped +because of a failure, in increasing intervals of 3, 6, 12, 24 and finally 30 seconds: + +@@snip [BackoffSupervisorDocSpec.scala](/akka-docs/src/test/scala/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-stop } + +The above is equivalent to this Java code: + +@@snip [BackoffSupervisorDocTest.java](/akka-docs/src/test/java/jdocs/pattern/BackoffSupervisorDocTest.java) { #backoff-imports } + +@@snip [BackoffSupervisorDocTest.java](/akka-docs/src/test/java/jdocs/pattern/BackoffSupervisorDocTest.java) { #backoff-stop } + +Using a `randomFactor` to add a little bit of additional variance to the backoff intervals +is highly recommended, in order to avoid multiple actors re-start at the exact same point in time, +for example because they were stopped due to a shared resource such as a database going down +and re-starting after the same configured interval. By adding additional randomness to the +re-start intervals the actors will start in slightly different points in time, thus avoiding +large spikes of traffic hitting the recovering shared database or other resource that they all need to contact. + +The `akka.pattern.BackoffSupervisor` actor can also be configured to stop and start the actor after a delay when the actor +crashes and the supervision strategy decides that it should restart. + +The following Scala snippet shows how to create a backoff supervisor which will start the given echo actor after it has crashed +because of some exception, in increasing intervals of 3, 6, 12, 24 and finally 30 seconds: + +@@snip [BackoffSupervisorDocSpec.scala](/akka-docs/src/test/scala/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-fail } + +The above is equivalent to this Java code: + +@@snip [BackoffSupervisorDocTest.java](/akka-docs/src/test/java/jdocs/pattern/BackoffSupervisorDocTest.java) { #backoff-imports } + +@@snip [BackoffSupervisorDocTest.java](/akka-docs/src/test/java/jdocs/pattern/BackoffSupervisorDocTest.java) { #backoff-fail } + +### Customization + +The `akka.pattern.BackoffOnFailureOptions` and `akka.pattern.BackoffOnRestartOptions` can be used to customize the behavior of the back-off supervisor actor. +Options are: +* `withAutoReset`: The backoff is reset if no failure/stop occurs within the duration. This is the default behaviour with `minBackoff` as default value +* `withManualReset`: The child must send `BackoffSupervisor.Reset` to its backoff supervisor (parent) +* `withSupervisionStrategy`: Sets a custom `OneForOneStrategy` (as each backoff supervisor only has one child). The default strategy uses the `akka.actor.SupervisorStrategy.defaultDecider` which stops and starts the child on exceptions. +* `withMaxNrOfRetries`: Sets the maximum number of retries until the supervisor will give up (`-1` is default which means no limit of retries). Note: This is set on the supervision strategy, so setting a different strategy resets the `maxNrOfRetries`. +* `withReplyWhileStopped`: By default all messages received while the child is stopped are forwarded to dead letters. With this set, the supervisor will reply to the sender instead. + +Only available on `BackoffOnStopOptions`: +* `withDefaultStoppingStrategy`: Sets a `OneForOneStrategy` with the stopping decider that stops the child on all exceptions. +* `withFinalStopMessage`: Allows to define a predicate to decide on finally stopping the child (and supervisor). Used for passivate sharded actors - see above. + +Some examples: + +@@snip [BackoffSupervisorDocSpec.scala](/akka-docs/src/test/scala/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-custom-stop } + +The above code sets up a back-off supervisor that requires the child actor to send a `akka.pattern.BackoffSupervisor.Reset` message +to its parent when a message is successfully processed, resetting the back-off. It also uses a default stopping strategy, any exception +will cause the child to stop. + +@@snip [BackoffSupervisorDocSpec.scala](/akka-docs/src/test/scala/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-custom-fail } + +The above code sets up a back-off supervisor that stops and starts the child after back-off if MyException is thrown, any other exception will be +escalated. The back-off is automatically reset if the child does not throw any errors within 10 seconds. diff --git a/akka-docs/src/main/paradox/general/actor-systems.md b/akka-docs/src/main/paradox/general/actor-systems.md index 83a1533064..3bcf3117f6 100644 --- a/akka-docs/src/main/paradox/general/actor-systems.md +++ b/akka-docs/src/main/paradox/general/actor-systems.md @@ -23,84 +23,73 @@ so create one per logical application. Like in an economic organization, actors naturally form hierarchies. One actor, which is to oversee a certain function in the program might want to split up its task into smaller, more manageable pieces. For this purpose, it starts child -actors which it supervises. While the details of supervision are explained -@ref:[here](supervision.md), we shall concentrate on the underlying concepts in -this section. The only prerequisite is to know that each actor has exactly one -supervisor, which is the actor that created it. +actors. The quintessential feature of actor systems is that tasks are split up and delegated until they become small enough to be handled in one piece. In doing so, not only is the task itself clearly structured, but the resulting actors can be reasoned about in terms of which messages they should process, how they -should react normally and how failure should be handled. If one actor does not -have the means for dealing with a certain situation, it sends a corresponding -failure message to its supervisor, asking for help. The recursive structure -then allows to handle failure at the right level. +should react normally and how failure should be handled. Compare this to layered software design which easily devolves into defensive programming with the aim of not leaking any failure out: if the problem is communicated to the right person, a better solution can be found than if trying to keep everything “under the carpet”. -Now, the difficulty in designing such a system is how to decide who should -supervise what. There is no single best solution, but there are a few +Now, the difficulty in designing such a system is how to decide how to +structure the work. There is no single best solution, but there are a few guidelines which might be helpful: - * If one actor manages the work another actor is doing, e.g. by passing on -sub-tasks, then the manager should supervise the child. The reason is that -the manager knows which kind of failures are expected and how to handle -them. * If one actor carries very important data (i.e. its state shall not be lost -if avoidable), this actor should source out any possibly dangerous sub-tasks -to children it supervises and handle failures of these children as -appropriate. Depending on the nature of the requests, it may be best to -create a new child for each request, which simplifies state management for -collecting the replies. This is known as the “Error Kernel Pattern” from -Erlang. + if avoidable), this actor should source out any possibly dangerous sub-tasks + to children and handle failures of these children as appropriate. Depending on + the nature of the requests, it may be best to create a new child for each request, + which simplifies state management for collecting the replies. This is known as the + “Error Kernel Pattern” from Erlang. * If one actor depends on another actor for carrying out its duty, it should -watch that other actor’s liveness and act upon receiving a termination -notice. This is different from supervision, as the watching party has no -influence on the supervisor strategy, and it should be noted that a -functional dependency alone is not a criterion for deciding where to place a -certain child actor in the hierarchy. - -There are always exceptions to these rules, but no matter whether you -follow the rules or break them, you should always have a reason. + watch that other actor’s liveness and act upon receiving a termination + notice. + * If one actor has multiple responsibilities each responsibility can often be pushed + into a separate child to make the logic and state more simple. ## Configuration Container The actor system as a collaborating ensemble of actors is the natural unit for managing shared facilities like scheduling services, configuration, logging, etc. Several actor systems with different configurations may co-exist within the -same JVM without problems, there is no global shared state within Akka itself. -Couple this with the transparent communication between actor systems—within one -node or across a network connection—to see that actor systems themselves can be -used as building blocks in a functional hierarchy. +same JVM without problems, there is no global shared state within Akka itself, +however the most common scenario will only involve a single actor system per JVM. + +Couple this with the transparent communication between actor systems — within one +node or across a network connection — and actor systems are a perfect fit to form +a distributed application. ## Actor Best Practices 1. Actors should be like nice co-workers: do their job efficiently without -bothering everyone else needlessly and avoid hogging resources. Translated -to programming this means to process events and generate responses (or more -requests) in an event-driven manner. Actors should not block (i.e. passively -wait while occupying a Thread) on some external entity—which might be a -lock, a network socket, etc.—unless it is unavoidable; in the latter case -see below. + bothering everyone else needlessly and avoid hogging resources. Translated + to programming this means to process events and generate responses (or more + requests) in an event-driven manner. Actors should not block (i.e. passively + wait while occupying a Thread) on some external entity—which might be a + lock, a network socket, etc.—unless it is unavoidable; in the latter case + see below. 2. Do not pass mutable objects between actors. In order to ensure that, prefer -immutable messages. If the encapsulation of actors is broken by exposing -their mutable state to the outside, you are back in normal Java concurrency -land with all the drawbacks. + immutable messages. If the encapsulation of actors is broken by exposing + their mutable state to the outside, you are back in normal Java concurrency + land with all the drawbacks. 3. Actors are made to be containers for behavior and state, embracing this -means to not routinely send behavior within messages (which may be tempting -using Scala closures). One of the risks is to accidentally share mutable -state between actors, and this violation of the actor model unfortunately -breaks all the properties which make programming in actors such a nice -experience. - 4. Top-level actors are the innermost part of your Error Kernel, so create them -sparingly and prefer truly hierarchical systems. This has benefits with -respect to fault-handling (both considering the granularity of configuration -and the performance) and it also reduces the strain on the guardian actor, -which is a single point of contention if over-used. + means to not routinely send behavior within messages (which may be tempting + using Scala closures). One of the risks is to accidentally share mutable + state between actors, and this violation of the actor model unfortunately + breaks all the properties which make programming in actors such a nice + experience. + 4. The top-level actor of the actor system is the innermost part of your + Error Kernel, it should only be responsible for starting the various + sub systems of your application, and not contain much logic in itself, + prefer truly hierarchical systems. This has benefits with + respect to fault-handling (both considering the granularity of configuration + and the performance) and it also reduces the strain on the guardian actor, + which is a single point of contention if over-used. ## What you should not concern yourself with @@ -114,10 +103,9 @@ while Akka does the heavy lifting under the hood. ## Terminating ActorSystem -When you know everything is done for your application, you can call the -`terminate` method of `ActorSystem`. That will run @ref:[`CoordinatedShutdown`](../actors.md#coordinated-shutdown) -followed by stopping the guardian actor, which in turn will recursively stop all its child actors, -and finally the system guardian. +When you know everything is done for your application, you can have the user guardian + actor stop, or call the `terminate` method of `ActorSystem`. That will run @ref:[`CoordinatedShutdown`](../actors.md#coordinated-shutdown) +stopping all running actors. If you want to execute some operations while terminating `ActorSystem`, look at @ref:[`CoordinatedShutdown`](../actors.md#coordinated-shutdown). diff --git a/akka-docs/src/main/paradox/general/actors.md b/akka-docs/src/main/paradox/general/actors.md index f08c70de6f..28f0354ff9 100644 --- a/akka-docs/src/main/paradox/general/actors.md +++ b/akka-docs/src/main/paradox/general/actors.md @@ -158,12 +158,9 @@ their parent. ## Supervisor Strategy -The final piece of an actor is its strategy for handling faults of its -children. Fault handling is then done transparently by Akka, applying one -of the strategies described in @ref:[Fault Tolerance](../typed/fault-tolerance.md) -for each incoming failure. -As this strategy is fundamental to how an actor system is structured, it -cannot be changed once an actor has been created. +The final piece of an actor is its a strategy for handling unexpected exceptions - failures. +Fault handling is then done transparently by Akka, applying one of the strategies described +in @ref:[Fault Tolerance](../typed/fault-tolerance.md) for each failure. ## When an Actor Terminates diff --git a/akka-docs/src/main/paradox/general/addressing.md b/akka-docs/src/main/paradox/general/addressing.md index 267a98b2b2..ce7fd834a7 100644 --- a/akka-docs/src/main/paradox/general/addressing.md +++ b/akka-docs/src/main/paradox/general/addressing.md @@ -1,12 +1,9 @@ # Actor References, Paths and Addresses This chapter describes how actors are identified and located within a possibly -distributed actor system. It ties into the central idea that -@ref:[Actor Systems](actor-systems.md) form intrinsic supervision hierarchies as well as that -communication between actors is transparent with respect to their placement -across multiple network nodes. +distributed Akka application. -![ActorPath.png](ActorPath.png) +![actor-paths-overview.png](../images/actor-paths-overview.png) The above image displays the relationship between the most important entities within an actor system, please read on for the details. @@ -15,11 +12,8 @@ within an actor system, please read on for the details. An actor reference is a subtype of `ActorRef`, whose foremost purpose is to support sending messages to the actor it represents. Each actor has access -to its canonical (local) reference through the `self` field; this -reference is also included as sender reference by default for all messages sent -to other actors. Conversely, during message processing the actor has access to -a reference representing the sender of the current message through the -`sender()` method. +to its canonical (local) reference through the `ActorContext.self` field; this +reference can be included in messages to other actors to get replies back. There are several different types of actor references that are supported depending on the configuration of the actor system: @@ -32,10 +26,6 @@ which support networking functions for those references which represent actors within the same JVM. In order to also be reachable when sent to other network nodes, these references include protocol and remote addressing information. - * There is a subtype of local actor references which is used for routers (i.e. -actors mixing in the `Router` trait). Its logical structure is the -same as for the aforementioned local references, but sending a message to -them dispatches to one of their children directly instead. * Remote actor references represent actors which are reachable using remote communication, i.e. sending messages to them will serialize the messages transparently and send them to the remote JVM. @@ -110,125 +100,28 @@ the creation ancestry of an actor, so it is completely deterministic as soon as the actor system’s remoting configuration (and with it the address component of the path) is set. -### Physical Actor Paths - -While the logical actor path describes the functional location within one actor -system, configuration-based remote deployment means that an actor may be -created on a different network host than its parent, i.e. within a different -actor system. In this case, following the actor path from the root guardian up -entails traversing the network, which is a costly operation. Therefore, each -actor also has a physical path, starting at the root guardian of the actor -system where the actual actor object resides. Using this path as sender -reference when querying other actors will let them reply directly to this -actor, minimizing delays incurred by routing. - -One important aspect is that a physical actor path never spans multiple actor -systems or JVMs. This means that the logical path (supervision hierarchy) and -the physical path (actor deployment) of an actor may diverge if one of its -ancestors is remotely supervised. - ### Actor path alias or symbolic link? As in some real file-systems you might think of a “path alias” or “symbolic link” for an actor, i.e. one actor may be reachable using more than one path. However, you should note that actor hierarchy is different from file system hierarchy. You cannot freely create actor paths like symbolic links to refer to arbitrary actors. -As described in the above logical and physical actor path sections, -an actor path must be either logical path which represents supervision hierarchy, or -physical path which represents actor deployment. ## How are Actor References obtained? There are two general categories to how actor references may be obtained: by -creating actors or by looking them up, where the latter functionality comes in -the two flavours of creating actor references from concrete actor paths and -querying the logical actor hierarchy. +creating actors or by looking them up through the @ref:[Receptionist](../typed/actor-discovery.md#receptionist). ### Creating Actors -An actor system is typically started by creating actors beneath the guardian -actor using the `ActorSystem.actorOf` method and then using -`ActorContext.actorOf` from within the created actors to spawn the actor +An actor system is started by creating actors beneath the user guardian +actor using the `ActorContext.spawn` method and then using +`ActorContext.spawn` from within the created actors to spawn the actor tree. These methods return a reference to the newly created actor. Each actor has direct access (through its `ActorContext`) to references for its parent, itself and its children. These references may be sent within messages to other actors, enabling those to reply directly. -### Looking up Actors by Concrete Path - -In addition, actor references may be looked up using the -`ActorSystem.actorSelection` method. The selection can be used for -communicating with said actor and the actor corresponding to the selection -is looked up when delivering each message. - -To acquire an `ActorRef` that is bound to the life-cycle of a specific actor -you need to send a message, such as the built-in `Identify` message, to the actor -and use the `sender()` reference of a reply from the actor. - -#### Absolute vs. Relative Paths - -In addition to `ActorSystem.actorSelection` there is also -`ActorContext.actorSelection`, which is available inside any actor as -`context.actorSelection`. This yields an actor selection much like its twin on -`ActorSystem`, but instead of looking up the path starting from the root -of the actor tree it starts out on the current actor. Path elements consisting -of two dots (`".."`) may be used to access the parent actor. You can for -example send a message to a specific sibling: - -``` -context.actorSelection("../brother") ! msg -``` - -Absolute paths may also be looked up on *context* in the usual way, i.e. - -```scala -context.actorSelection("/user/serviceA") ! msg -``` - -will work as expected. - -### Querying the Logical Actor Hierarchy - -Since the actor system forms a file-system like hierarchy, matching on paths is -possible in the same way as supported by Unix shells: you may replace (parts -of) path element names with wildcards (*«*»* and *«?»*) to formulate a -selection which may match zero or more actual actors. Because the result is not -a single actor reference, it has a different type `ActorSelection` and -does not support the full set of operations an `ActorRef` does. -Selections may be formulated using the `ActorSystem.actorSelection` and -`ActorContext.actorSelection` methods and do support sending messages: - -``` -context.actorSelection("../*") ! msg -``` - -will send *msg* to all siblings including the current actor. As for references -obtained using *actorSelection*, a traversal of the supervision hierarchy is done in -order to perform the message send. As the exact set of actors which match a -selection may change even while a message is making its way to the recipients, -it is not possible to watch a selection for liveliness changes. In order to do -that, resolve the uncertainty by sending a request and gathering all answers, -extracting the sender references, and then watch all discovered concrete -actors. This scheme of resolving a selection may be improved upon in a future -release. - - -### Summary: `actorOf` vs. `actorSelection` - -@@@ note - -What the above sections described in some detail can be summarized and -memorized as follows: - - * `actorOf` only ever creates a new actor, and it creates it as a direct -child of the context on which this method is invoked (which may be any -actor or actor system). - * `actorSelection` only ever looks up existing actors when messages are -delivered, i.e. does not create actors, or verify existence of actors -when the selection is created. - -@@@ - ## Actor Reference and Path Equality Equality of `ActorRef` match the intention that an `ActorRef` corresponds to @@ -248,40 +141,6 @@ of the target actor is not taken into account when comparing actor paths. When an actor is terminated, its reference will point to the dead letter mailbox, DeathWatch will publish its final transition and in general it is not expected to come back to life again (since the actor life cycle does not allow this). -While it is possible to create an actor at a later time with an identical -path—due to it being impossible to enforce the opposite without keeping -the set of all actors ever created available—this is not good practice: -messages sent with `actorSelection` to an actor which “died” suddenly start to work -again, but without any guarantee of ordering between this transition and any -other event, hence the new inhabitant of the path may receive messages which were destined for the -previous tenant. - -It may be the right thing to do in very specific circumstances, but make sure -to confine the handling of this precisely to the actor’s supervisor, because -that is the only actor which can reliably detect proper deregistration of the -name, before which creation of the new child will fail. - -It may also be required during testing, when the test subject depends on being -instantiated at a specific path. In that case it is best to mock its supervisor -so that it will forward the Terminated message to the appropriate point in the -test procedure, enabling the latter to await proper deregistration of the name. - -## The Interplay with Remote Deployment - -When an actor creates a child, the actor system’s deployer will decide whether -the new actor resides in the same JVM or on another node. In the second case, -creation of the actor will be triggered via a network connection to happen in a -different JVM and consequently within a different actor system. The remote -system will place the new actor below a special path reserved for this purpose -and the supervisor of the new actor will be a remote actor reference -(representing that actor which triggered its creation). In this case, -`context.parent` (the supervisor reference) and -`context.path.parent` (the parent node in the actor’s path) do not -represent the same actor. However, looking up the child’s name within the -supervisor will find it on the remote node, preserving logical structure e.g. -when sending to an unresolved actor reference. - -![RemoteDeployment.png](RemoteDeployment.png) ## What is the Address part used for? @@ -316,11 +175,4 @@ supervisors are remote actor references The need to structure the name space for actors like this arises from a central and very simple design goal: everything in the hierarchy is an actor, and all -actors function in the same way. Hence you can not only look up the actors you -created, you can also look up the system guardian and send it a message (which -it will dutifully discard in this case). This powerful principle means that -there are no quirks to remember, it makes the whole system more uniform and -consistent. - -If you want to read more about the top-level structure of an actor system, have -a look at @ref:[The Top-Level Supervisors](supervision.md#toplevel-supervisors). +actors function in the same way. diff --git a/akka-docs/src/main/paradox/general/configuration.md b/akka-docs/src/main/paradox/general/configuration.md index 57c077be3e..a5bfa49351 100644 --- a/akka-docs/src/main/paradox/general/configuration.md +++ b/akka-docs/src/main/paradox/general/configuration.md @@ -5,26 +5,15 @@ are provided. Later on you might need to amend the settings to change the defaul or adapt for specific runtime environments. Typical examples of settings that you might amend: - * log level and logger backend + * log level and logger backend for the Akka internals * enable remoting * message serializers - * definition of routers * tuning of dispatchers -Akka uses the [Typesafe Config Library](https://github.com/typesafehub/config), which might also be a good choice +Akka uses the [Typesafe Config Library](https://github.com/lightbend/config), which might also be a good choice for the configuration of your own application or library built with or without -Akka. This library is implemented in Java with no external dependencies; you -should have a look at its documentation (in particular about [ConfigFactory](https://lightbend.github.io/config/latest/api/com/typesafe/config/ConfigFactory.html)), -which is only summarized in the following. - -@@@ warning - -If you use Akka from the Scala REPL from the 2.9.x series, -and you do not provide your own ClassLoader to the ActorSystem, -start the REPL with "-Yrepl-sync" to work around a deficiency in -the REPLs provided Context ClassLoader. - -@@@ +Akka. This library is implemented in Java with no external dependencies; +This is only a summary of the most important parts for more details see [the config library docs](https://github.com/lightbend/config/blob/master/README.md). ## Where configuration is read from @@ -88,6 +77,9 @@ A custom `application.conf` might look like this: akka { + # Logger config for Akka internals and classic actors, the new API relies + # directly on SLF4J and your config for the logger backend. + # Loggers to register at boot time (akka.event.Logging$DefaultLogger logs # to STDOUT) loggers = ["akka.event.slf4j.Slf4jLogger"] @@ -149,12 +141,13 @@ If the system or config property `akka.log-config-on-start` is set to `on`, then complete configuration is logged at INFO level when the actor system is started. This is useful when you are uncertain of what configuration is used. +@@@div { .group-scala } + If in doubt, you can inspect your configuration objects before or after using them to construct an actor system: -@@@vars ``` -Welcome to Scala $scala.binary_version$ (Java HotSpot(TM) 64-Bit Server VM, Java 1.8.0). +Welcome to Scala 2.12 (Java HotSpot(TM) 64-Bit Server VM, Java 1.8.0). Type in expressions to have them evaluated. Type :help for more information. @@ -174,6 +167,7 @@ res1: java.lang.String = } } ``` + @@@ The comments preceding every item give detailed information about the origin of @@ -181,11 +175,12 @@ the setting (file & line number) plus possible comments which were present, e.g. in the reference configuration. The settings as merged with the reference and parsed by the actor system can be displayed like this: -```java -final ActorSystem system = ActorSystem.create(); -System.out.println(system.settings()); -// this is a shortcut for system.settings().config().root().render() -``` +Scala +: @@snip [ConfigDocSpec.scala](/akka-docs/src/test/scala/docs/config/ConfigDocSpec.scala) { #dump-config } + +Java +: @@snip [ConfigDocTest.java](/akka-docs/src/test/java/jdocs/config/ConfigDocTest.java) { #dump-config } + ## A Word About ClassLoaders @@ -203,7 +198,7 @@ This implies that putting Akka on the boot class path will yield ## Application specific settings The configuration can also be used for application specific settings. -A good practice is to place those settings in an @ref:[Extension](../extending-akka.md#extending-akka-settings). +A good practice is to place those settings in an @ref:[Extension](../extending-akka.md#extending-akka-settings). ## Configuring multiple ActorSystem @@ -229,12 +224,11 @@ my.own.setting = 42 my.other.setting = "hello" ``` -```scala -val config = ConfigFactory.load() -val app1 = ActorSystem("MyApp1", config.getConfig("myapp1").withFallback(config)) -val app2 = ActorSystem("MyApp2", - config.getConfig("myapp2").withOnlyPath("akka").withFallback(config)) -``` +Scala +: @@snip [ConfigDocSpec.scala](/akka-docs/src/test/scala/docs/config/ConfigDocSpec.scala) { #separate-apps } + +Java +: @@snip [ConfigDocTest.java](/akka-docs/src/test/java/jdocs/config/ConfigDocTest.java) { #separate-apps } These two samples demonstrate different variations of the “lift-a-subtree” trick: in the first case, the configuration accessible from within the actor @@ -270,7 +264,13 @@ substitutions. You may also specify and parse the configuration programmatically in other ways when instantiating the `ActorSystem`. -@@snip [ConfigDocSpec.scala](/akka-docs/src/test/scala/docs/config/ConfigDocSpec.scala) { #imports #custom-config } + +Scala +: @@snip [ConfigDocSpec.scala](/akka-docs/src/test/scala/docs/config/ConfigDocSpec.scala) { #imports #custom-config } + +Java +: @@snip [ConfigDocTest.java](/akka-docs/src/test/java/jdocs/config/ConfigDocTest.java) { #imports #custom-config } + ## Reading configuration from a custom location @@ -313,7 +313,12 @@ you could put a config string in code using You can also combine your custom config with the usual config, that might look like: -@@snip [ConfigDoc.java](/akka-docs/src/test/java/jdocs/config/ConfigDoc.java) { #java-custom-config } +Scala +: @@snip [ConfigDocSpec.scala](/akka-docs/src/test/scala/docs/config/ConfigDocSpec.scala) { #custom-config-2 } + +Java +: @@snip [ConfigDocTest.java](/akka-docs/src/test/java/jdocs/config/ConfigDocTest.java) { #custom-config-2 } + When working with `Config` objects, keep in mind that there are three "layers" in the cake: @@ -340,41 +345,6 @@ Includes at the top of `application.conf` will be overridden by the rest of `application.conf`, while those at the bottom will override the earlier stuff. -## Actor Deployment Configuration - -Deployment settings for specific actors can be defined in the `akka.actor.deployment` -section of the configuration. In the deployment section it is possible to define -things like dispatcher, mailbox, router settings, and remote deployment. -Configuration of these features are described in the chapters detailing corresponding -topics. An example may look like this: - -@@snip [ConfigDocSpec.scala](/akka-docs/src/test/scala/docs/config/ConfigDocSpec.scala) { #deployment-section } - -@@@ note - -The deployment section for a specific actor is identified by the -path of the actor relative to `/user`. - -@@@ - -You can use asterisks as wildcard matches for the actor path sections, so you could specify: -`/*/sampleActor` and that would match all `sampleActor` on that level in the hierarchy. -In addition, please note: - - * you can also use wildcards in the last position to match all actors at a certain level: `/someParent/*` - * you can use double-wildcards in the last position to match all child actors and their children -recursively: `/someParent/**` - * non-wildcard matches always have higher priority to match than wildcards, and single wildcard matches -have higher priority than double-wildcards, so: `/foo/bar` is considered **more specific** than -`/foo/*`, which is considered **more specific** than `/foo/**`. Only the highest priority match is used - * wildcards **cannot** be used to partially match section, like this: `/foo*/bar`, `/f*o/bar` etc. - -@@@ note - -Double-wildcards can only be placed in the last position. - -@@@ - ## Listing of the Reference Configuration Each Akka module has a reference configuration file with the default values. @@ -384,31 +354,61 @@ Each Akka module has a reference configuration file with the default values. @@snip [reference.conf](/akka-actor/src/main/resources/reference.conf) + +### akka-actor-typed + +@@snip [reference.conf](/akka-actor-typed/src/main/resources/reference.conf) + + +### akka-cluster-typed + +@@snip [reference.conf](/akka-cluster-typed/src/main/resources/reference.conf) + ### akka-cluster @@snip [reference.conf](/akka-cluster/src/main/resources/reference.conf) + +### akka-discovery + +@@snip [reference.conf](/akka-discovery/src/main/resources/reference.conf) + + +### akka-coordination + +@@snip [reference.conf](/akka-coordination/src/main/resources/reference.conf) + ### akka-multi-node-testkit @@snip [reference.conf](/akka-multi-node-testkit/src/main/resources/reference.conf) + +### akka-persistence-typed + +@@snip [reference.conf](/akka-persistence-typed/src/main/resources/reference.conf) + ### akka-persistence @@snip [reference.conf](/akka-persistence/src/main/resources/reference.conf) - -### akka-remote + +### akka-persistence-query -@@snip [reference.conf](/akka-remote/src/main/resources/reference.conf) { #shared #classic type=none } +@@snip [reference.conf](/akka-persistence-query/src/main/resources/reference.conf) -### akka-remote (artery) +### akka-remote artery @@snip [reference.conf](/akka-remote/src/main/resources/reference.conf) { #shared #artery type=none } + +### akka-remote classic (deprecated) + +@@snip [reference.conf](/akka-remote/src/main/resources/reference.conf) { #shared #classic type=none } + ### akka-testkit @@ -424,6 +424,11 @@ Each Akka module has a reference configuration file with the default values. @@snip [reference.conf](/akka-cluster-tools/src/main/resources/reference.conf) + +### akka-cluster-sharding-typed + +@@snip [reference.conf](/akka-cluster-sharding-typed/src/main/resources/reference.conf) + ### akka-cluster-sharding @@ -433,3 +438,14 @@ Each Akka module has a reference configuration file with the default values. ### akka-distributed-data @@snip [reference.conf](/akka-distributed-data/src/main/resources/reference.conf) + + +### akka-stream + +@@snip [reference.conf](/akka-stream/src/main/resources/reference.conf) + + +### akka-stream-testkit + +@@snip [reference.conf](/akka-stream-testkit/src/main/resources/reference.conf) + diff --git a/akka-docs/src/main/paradox/general/jmm.md b/akka-docs/src/main/paradox/general/jmm.md index 9b91cd8483..af72696576 100644 --- a/akka-docs/src/main/paradox/general/jmm.md +++ b/akka-docs/src/main/paradox/general/jmm.md @@ -65,8 +65,13 @@ Such are the perils of synchronized. Since Akka runs on the JVM there are still some rules to be followed. - * Closing over internal Actor state and exposing it to other threads +Most importantly, you must not close over internal Actor state and exposing it to other threads: + +Scala +: @@snip [SharedMutableStateDocSpec.scala](/akka-docs/src/test/scala/docs/actor/typed/SharedMutableStateDocSpec.scala) { #mutable-state } + +Java +: @@snip [DistributedDataDocTest.java](/akka-docs/src/test/java/jdocs/actor/typed/SharedMutableStateDocTest.java) { #mutable-state } -@@snip [SharedMutableStateDocSpec.scala](/akka-docs/src/test/scala/docs/actor/SharedMutableStateDocSpec.scala) { #mutable-state } * Messages **should** be immutable, this is to avoid the shared mutable state trap. diff --git a/akka-docs/src/main/paradox/general/message-delivery-reliability.md b/akka-docs/src/main/paradox/general/message-delivery-reliability.md index f3e9b70ea7..6cf09fe069 100644 --- a/akka-docs/src/main/paradox/general/message-delivery-reliability.md +++ b/akka-docs/src/main/paradox/general/message-delivery-reliability.md @@ -275,9 +275,12 @@ acknowledgement * a way for the receiver to detect and discard duplicates The third becomes necessary by virtue of the acknowledgements not being guaranteed -to arrive either. An ACK-RETRY protocol with business-level acknowledgements is -supported by @ref:[At-Least-Once Delivery](../persistence.md#at-least-once-delivery) of the Akka Persistence module. Duplicates can be -detected by tracking the identifiers of messages sent via @ref:[At-Least-Once Delivery](../persistence.md#at-least-once-delivery). +to arrive either. + +An ACK-RETRY protocol with business-level acknowledgements and de-duplication using identifiers is +supported by the @ref:[At-Least-Once Delivery](../persistence.md#at-least-once-delivery) of the Classic Akka Persistence module. +Corresponding functionality for typed has not yet been implemented (see [issue #20984](https://github.com/akka/akka/issues/20984)). + Another way of implementing the third part would be to make processing the messages idempotent on the level of the business logic. @@ -350,8 +353,8 @@ local system (if no network connection can be established) or the remote one Every time an actor does not terminate by its own decision, there is a chance that some messages which it sends to itself are lost. There is one which happens quite easily in complex shutdown scenarios that is usually benign: -seeing a `akka.dispatch.Terminate` message dropped means that two -termination requests were given, but only one can succeed. In the +seeing instances of a graceful stop command for an actor being dropped means that two +stop requests were given, but only one can succeed. In the same vein, you might see `akka.actor.Terminated` messages from children while stopping a hierarchy of actors turning up in dead letters if the parent is still watching the child when the parent terminates. diff --git a/akka-docs/src/main/paradox/general/remoting.md b/akka-docs/src/main/paradox/general/remoting.md index 30ac482a4b..f0416095bc 100644 --- a/akka-docs/src/main/paradox/general/remoting.md +++ b/akka-docs/src/main/paradox/general/remoting.md @@ -21,9 +21,7 @@ for a detailed discussion on why the second approach is bound to fail. What is true of Akka need not be true of the application which uses it, since designing for distributed execution poses some restrictions on what is possible. The most obvious one is that all messages sent over the wire must be -serializable. While being a little less obvious this includes closures which -are used as actor factories (i.e. within `Props`) if the actor is to be -created on a remote node. +serializable. Another consequence is that everything needs to be aware of all interactions being fully asynchronous, which in a computer network might mean that it may @@ -32,19 +30,6 @@ configuration). It also means that the probability for a message to be lost is much higher than within one JVM, where it is close to zero (still: no hard guarantee!). -## How is Remoting Used? - -We took the idea of transparency to the limit in that there is nearly no API -for the remoting layer of Akka: it is purely driven by configuration. Just -write your application according to the principles outlined in the previous -sections, then specify remote deployment of actor sub-trees in the -configuration file. This way, your application can be scaled out without having -to touch the code. The only piece of the API which allows programmatic -influence on remote deployment is that `Props` contain a field which may -be set to a specific `Deploy` instance; this has the same effect as -putting an equivalent deployment into the configuration file (if both are -given, configuration file wins). - ## Peer-to-Peer vs. Client-Server @@ -74,11 +59,4 @@ In addition to being able to run different parts of an actor system on different nodes of a cluster, it is also possible to scale up onto more cores by multiplying actor sub-trees which support parallelization (think for example a search engine processing different queries in parallel). The clones can then -be routed to in different fashions, e.g. round-robin. The only thing necessary -to achieve this is that the developer needs to declare a certain actor as -“withRouter”, then—in its stead—a router actor will be created which will spawn -up a configurable number of children of the desired type and route to them in -the configured fashion. Once such a router has been declared, its configuration -can be freely overridden from the configuration file, including mixing it with -the remote deployment of (some of) the children. Read more about -this in @ref:[Routing](../routing.md). +be routed to in different fashions, e.g. round-robin. See @ref:[Routing](../typed/routers.md) for more details. diff --git a/akka-docs/src/main/paradox/general/supervision.md b/akka-docs/src/main/paradox/general/supervision.md index 363d3de07f..e9e07b3b50 100644 --- a/akka-docs/src/main/paradox/general/supervision.md +++ b/akka-docs/src/main/paradox/general/supervision.md @@ -2,121 +2,55 @@ This chapter outlines the concept behind supervision, the primitives offered and their semantics. For details on how that translates into real code, please -refer to the corresponding chapters for Scala and Java APIs. +refer to @ref:[supervision](../typed/fault-tolerance.md). -## Sample project - -You can look at the -@extref[Supervision example project](samples:akka-samples-supervision-java) -to see what this looks like in practice. +Supervision has changed since classic, for details on classic supervision see @ref:[Classic Supervision](../supervision-classic.md) ## What Supervision Means -As described in @ref:[Actor Systems](actor-systems.md) supervision describes a dependency -relationship between actors: the supervisor delegates tasks to subordinates and -therefore must respond to their failures. When a subordinate detects a failure -(i.e. throws an exception), it suspends itself and all its subordinates and -sends a message to its supervisor, signaling failure. Depending on the nature -of the work to be supervised and the nature of the failure, the supervisor has -a choice of the following four options: +There are two categories of exception that can happen in an actor: - 1. Resume the subordinate, keeping its accumulated internal state - 2. Restart the subordinate, clearing out its accumulated internal state - 3. Stop the subordinate permanently - 4. Escalate the failure, thereby failing itself + 1. Input validation errors, expected exceptions which can be handled with a regular try-catch + or other language and standard library tools. + 1. Unexpected **failures**, for example a network resource being unavailable, a disk write failing or perhaps + a bug in the application logic. -It is important to always view an actor as part of a supervision hierarchy, -which explains the existence of the fourth choice (as a supervisor also is -subordinate to another supervisor higher up) and has implications on the first -three: resuming an actor resumes all its subordinates, restarting an actor -entails restarting all its subordinates (but see below for more details), -similarly terminating an actor will also terminate all its subordinates. It -should be noted that the default behavior of the `preRestart` hook of the -`Actor` class is to terminate all its children before restarting, but -this hook can be overridden; the recursive restart applies to all children left -after this hook has been executed. +Supervision deals with failures and should be separated from the business logic while validating data and handling +of expected exceptions is a vital part of the business logic. Therefore supervision is added to an actor as decoration +rather than something that is intermingled with the message processing logic of the actor. -Each supervisor is configured with a function translating all possible failure -causes (i.e. exceptions) into one of the four choices given above; notably, -this function does not take the failed actor’s identity as an input. It is -quite easy to come up with examples of structures where this might not seem -flexible enough, e.g. wishing for different strategies to be applied to -different subordinates. At this point it is vital to understand that -supervision is about forming a recursive fault handling structure. If you try -to do too much at one level, it will become hard to reason about, hence the -recommended way in this case is to add a level of supervision. +Depending on the nature of the work to be supervised and the nature of the failure, supervision +provides the following three strategies: -Akka implements a specific form called “parental supervision”. Actors can only -be created by other actors—where the top-level actor is provided by the -library—and each created actor is supervised by its parent. This restriction -makes the formation of actor supervision hierarchies implicit and encourages -sound design decisions. It should be noted that this also guarantees that -actors cannot be orphaned or attached to supervisors from the outside, which -might otherwise catch them unawares. In addition, this yields a natural and -clean shutdown procedure for (sub-trees of) actor applications. + 1. Resume the actor, keeping its accumulated internal state + 2. Restart the actor, clearing out its accumulated internal state, with a potential delay starting again + 3. Stop the actor permanently -@@@ warning +Since actors are part of a hierarchy it can often make sense to propagate +the permanent failures upwards, if all children of an actor has stopped +unexpectedly it may make sense for the actor itself to restart or stop to +get back to a functional state. This can achieved through a combination of +supervision and watching the children to get notified when they terminate. +An example of this can be found in @ref:[Bubble failures up through the hierarchy](../typed/fault-tolerance.md#bubble). -Supervision related parent-child communication happens by special system -messages that have their own mailboxes separate from user messages. This -implies that supervision related events are not deterministically -ordered relative to ordinary messages. In general, the user cannot influence -the order of normal messages and failure notifications. For details and -example see the @ref:[Discussion: Message Ordering](message-delivery-reliability.md#message-ordering) section. +## The Top-Level actors -@@@ +An actor system will during its creation start at least two actors. - -## The Top-Level Supervisors +### `/user`: the user guardian cator -![guardians.png](guardians.png) +This is the top level user provided actor, meant to bootstrap the application +by spawning subsystems as children. When the user guardian stops the entire +actor system is shut down. -An actor system will during its creation start at least three actors, shown in -the image above. For more information about the consequences for actor paths -see @ref:[Top-Level Scopes for Actor Paths](addressing.md#toplevel-paths). - - -### `/user`: The Guardian Actor - -The actor which is probably most interacted with is the parent of all -user-created actors, the guardian named `"/user"`. Actors created using -`system.actorOf()` are children of this actor. This means that when this -guardian terminates, all normal actors in the system will be shutdown, too. It -also means that this guardian’s supervisor strategy determines how the -top-level normal actors are supervised. Since Akka 2.1 it is possible to -configure this using the setting `akka.actor.guardian-supervisor-strategy`, -which takes the fully-qualified class-name of a -`SupervisorStrategyConfigurator`. When the guardian escalates a failure, -the root guardian’s response will be to terminate the guardian, which in effect -will shut down the whole actor system. - -### `/system`: The System Guardian +### `/system`: the system guardian This special guardian has been introduced in order to achieve an orderly shut-down sequence where logging remains active while all normal actors terminate, even though logging itself is implemented using actors. This is realized by having the system guardian watch the user guardian and initiate its own -shut-down upon reception of the `Terminated` message. The top-level -system actors are supervised using a strategy which will restart indefinitely -upon all types of `Exception` except for -`ActorInitializationException` and `ActorKilledException`, which -will terminate the child in question. All other throwables are escalated, -which will shut down the whole actor system. - -### `/`: The Root Guardian - -The root guardian is the grand-parent of all so-called “top-level” actors and -supervises all the special actors mentioned in @ref:[Top-Level Scopes for Actor Paths](addressing.md#toplevel-paths) using the -`SupervisorStrategy.stoppingStrategy`, whose purpose is to terminate the -child upon any type of `Exception`. All other throwables will be -escalated … but to whom? Since every real actor has a supervisor, the -supervisor of the root guardian cannot be a real actor. And because this means -that it is “outside of the bubble”, it is called the “bubble-walker”. This is a -synthetic `ActorRef` which in effect stops its child upon the first sign -of trouble and sets the actor system’s `isTerminated` status to `true` as -soon as the root guardian is fully terminated (all children recursively -stopped). +shut-down upon having seen the user guardian stop. ## What Restarting Means @@ -132,8 +66,8 @@ Unless the failure is specifically recognizable, the third cause cannot be ruled out, which leads to the conclusion that the internal state needs to be cleared out. If the supervisor decides that its other children or itself is not affected by the corruption—e.g. because of conscious application of the error -kernel pattern—it is therefore best to restart the child. This is carried out -by creating a new instance of the underlying `Actor` class and replacing +kernel pattern—it is therefore best to restart the actor. This is carried out +by creating a new instance of the underlying `Behavior` class and replacing the failed instance with the fresh one inside the child’s `ActorRef`; the ability to do this is one of the reasons for encapsulating actors within special references. The new actor then resumes processing its mailbox, meaning @@ -141,22 +75,6 @@ that the restart is not visible outside of the actor itself with the notable exception that the message during which the failure occurred is not re-processed. -The precise sequence of events during a restart is the following: - - 1. suspend the actor (which means that it will not process normal messages until -resumed), and recursively suspend all children - 2. call the old instance’s `preRestart` hook (defaults to sending -termination requests to all children and calling `postStop`) - 3. wait for all children which were requested to terminate (using -`context.stop()`) during `preRestart` to actually terminate; -this—like all actor operations—is non-blocking, the termination notice from -the last killed child will effect the progression to the next step - 4. create new actor instance by invoking the originally provided factory again - 5. invoke `postRestart` on the new instance (which by default also calls `preStart`) - 6. send restart request to all children which were not killed in step 3; -restarted children will follow the same process recursively, from step 2 - 7. resume the actor - ## What Lifecycle Monitoring Means @@@ note @@ -183,145 +101,6 @@ message will be delivered irrespective of the order in which the monitoring request and target’s termination occur, i.e. you still get the message even if at the time of registration the target is already dead. -Monitoring is particularly useful if a supervisor cannot restart its -children and has to terminate them, e.g. in case of errors during actor -initialization. In that case it should monitor those children and re-create -them or schedule itself to retry this at a later time. -Another common use case is that an actor needs to fail in the absence of an -external resource, which may also be one of its own children. If a third party -terminates a child by way of the `system.stop(child)` method or sending a -`PoisonPill`, the supervisor might well be affected. - -### Delayed restarts with the BackoffSupervisor pattern -Provided as a built-in pattern the `akka.pattern.BackoffSupervisor` implements the so-called -*exponential backoff supervision strategy*, starting a child actor again when it fails, each time with a growing time delay between restarts. - -This pattern is useful when the started actor fails [1] because some external resource is not available, -and we need to give it some time to start-up again. One of the prime examples when this is useful is -when a @ref:[PersistentActor](../persistence.md) fails (by stopping) with a persistence failure - which indicates that -the database may be down or overloaded, in such situations it makes most sense to give it a little bit of time -to recover before the persistent actor is started. - -> [1] A failure can be indicated in two different ways; by an actor stopping or crashing. - -#### Supervision strategies - -There are two basic supervision strategies available for backoff: - -* 'On failure': The supervisor will terminate and then start the supervised actor if it crashes. If the supervised actor stops normally (e.g. through `context.stop`), the supervisor will be terminated and no further attempt to start the supervised actor will be done. -* 'On stop': The supervisor will terminate and then start the supervised actor if it terminates in any way (consider this for `PersistentActor` since they stop on persistence failures instead of crashing) - -To note that this supervision strategy does not restart the actor but rather stops and starts it. Be aware of it if you -use @scala[`Stash` trait’s] @java[`AbstractActorWithStash`] in combination with the backoff supervision strategy. -The `preRestart` hook will not be executed if the supervised actor fails or stops and you will miss the opportunity -to unstash the messages. - -#### Sharding -If the 'on stop' strategy is used for sharded actors a final termination message should be configured and used to terminate the actor on passivation. Otherwise the supervisor will just stop and start the actor again. - -The termination message is configured with: - -@@snip [BackoffSupervisorDocSpec.scala](/akka-docs/src/test/scala/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-sharded } - -And must be used for passivation: - -@@snip [BackoffSupervisorDocSpec.scala](/akka-docs/src/test/scala/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-sharded-passivation } - -#### Simple backoff - -The following Scala snippet shows how to create a backoff supervisor which will start the given echo actor after it has stopped -because of a failure, in increasing intervals of 3, 6, 12, 24 and finally 30 seconds: - -@@snip [BackoffSupervisorDocSpec.scala](/akka-docs/src/test/scala/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-stop } - -The above is equivalent to this Java code: - -@@snip [BackoffSupervisorDocTest.java](/akka-docs/src/test/java/jdocs/pattern/BackoffSupervisorDocTest.java) { #backoff-imports } - -@@snip [BackoffSupervisorDocTest.java](/akka-docs/src/test/java/jdocs/pattern/BackoffSupervisorDocTest.java) { #backoff-stop } - -Using a `randomFactor` to add a little bit of additional variance to the backoff intervals -is highly recommended, in order to avoid multiple actors re-start at the exact same point in time, -for example because they were stopped due to a shared resource such as a database going down -and re-starting after the same configured interval. By adding additional randomness to the -re-start intervals the actors will start in slightly different points in time, thus avoiding -large spikes of traffic hitting the recovering shared database or other resource that they all need to contact. - -The `akka.pattern.BackoffSupervisor` actor can also be configured to stop and start the actor after a delay when the actor -crashes and the supervision strategy decides that it should restart. - -The following Scala snippet shows how to create a backoff supervisor which will start the given echo actor after it has crashed -because of some exception, in increasing intervals of 3, 6, 12, 24 and finally 30 seconds: - -@@snip [BackoffSupervisorDocSpec.scala](/akka-docs/src/test/scala/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-fail } - -The above is equivalent to this Java code: - -@@snip [BackoffSupervisorDocTest.java](/akka-docs/src/test/java/jdocs/pattern/BackoffSupervisorDocTest.java) { #backoff-imports } - -@@snip [BackoffSupervisorDocTest.java](/akka-docs/src/test/java/jdocs/pattern/BackoffSupervisorDocTest.java) { #backoff-fail } - -#### Customization - -The `akka.pattern.BackoffOnFailureOptions` and `akka.pattern.BackoffOnRestartOptions` can be used to customize the behavior of the back-off supervisor actor. -Options are: -* `withAutoReset`: The backoff is reset if no failure/stop occurs within the duration. This is the default behaviour with `minBackoff` as default value -* `withManualReset`: The child must send `BackoffSupervisor.Reset` to its backoff supervisor (parent) -* `withSupervisionStrategy`: Sets a custom `OneForOneStrategy` (as each backoff supervisor only has one child). The default strategy uses the `akka.actor.SupervisorStrategy.defaultDecider` which stops and starts the child on exceptions. -* `withMaxNrOfRetries`: Sets the maximum number of retries until the supervisor will give up (`-1` is default which means no limit of retries). Note: This is set on the supervision strategy, so setting a different strategy resets the `maxNrOfRetries`. -* `withReplyWhileStopped`: By default all messages received while the child is stopped are forwarded to dead letters. With this set, the supervisor will reply to the sender instead. - -Only available on `BackoffOnStopOptions`: -* `withDefaultStoppingStrategy`: Sets a `OneForOneStrategy` with the stopping decider that stops the child on all exceptions. -* `withFinalStopMessage`: Allows to define a predicate to decide on finally stopping the child (and supervisor). Used for passivate sharded actors - see above. - -Some examples: - -@@snip [BackoffSupervisorDocSpec.scala](/akka-docs/src/test/scala/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-custom-stop } - -The above code sets up a back-off supervisor that requires the child actor to send a `akka.pattern.BackoffSupervisor.Reset` message -to its parent when a message is successfully processed, resetting the back-off. It also uses a default stopping strategy, any exception -will cause the child to stop. - -@@snip [BackoffSupervisorDocSpec.scala](/akka-docs/src/test/scala/docs/pattern/BackoffSupervisorDocSpec.scala) { #backoff-custom-fail } - -The above code sets up a back-off supervisor that stops and starts the child after back-off if MyException is thrown, any other exception will be -escalated. The back-off is automatically reset if the child does not throw any errors within 10 seconds. - -## One-For-One Strategy vs. All-For-One Strategy - -There are two classes of supervision strategies which come with Akka: -`OneForOneStrategy` and `AllForOneStrategy`. Both are configured -with a mapping from exception type to supervision directive (see -[above](#supervision-directives)) and limits on how often a child is allowed to fail -before terminating it. The difference between them is that the former applies -the obtained directive only to the failed child, whereas the latter applies it -to all siblings as well. Normally, you should use the -`OneForOneStrategy`, which also is the default if none is specified -explicitly. - -The `AllForOneStrategy` is applicable in cases where the ensemble of -children has such tight dependencies among them, that a failure of one child -affects the function of the others, i.e. they are inextricably linked. Since a -restart does not clear out the mailbox, it often is best to terminate the children -upon failure and re-create them explicitly from the supervisor (by watching the -children’s lifecycle); otherwise you have to make sure that it is no problem -for any of the actors to receive a message which was queued before the restart -but processed afterwards. - -Normally stopping a child (i.e. not in response to a failure) will not -automatically terminate the other children in an all-for-one strategy; this can -be done by watching their lifecycle: if the `Terminated` message -is not handled by the supervisor, it will throw a `DeathPactException` -which (depending on its supervisor) will restart it, and the default -`preRestart` action will terminate all children. Of course this can be -handled explicitly as well. - -Please note that creating one-off actors from an all-for-one supervisor entails -that failures escalated by the temporary actor will affect all the permanent -ones. If this is not desired, install an intermediate supervisor; this can very -be done by declaring a router of size 1 for the worker, see -@ref:[Routing](../routing.md). diff --git a/akka-docs/src/main/paradox/images/actor-paths-overview.png b/akka-docs/src/main/paradox/images/actor-paths-overview.png new file mode 100644 index 0000000000000000000000000000000000000000..1553b5fab249f0ae753035e19f37e8cc24202359 GIT binary patch literal 164265 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%0D752?G(@SgO`sFTdj5H3eacW{(QvTW` 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�odzmGpZ}VPYb@c=LK` z*~1%>|K66JOMbVLU48b{mk^gcS;BCz&`&PRsuk=|7$M^O;Kp^e8?(8m|8D(vXZhUN z_gTN672n>KynJijGv(;LrMuIAJel%$P5k9uKYg6;gNvL`J`E2n&huH^g*0TrZe?I( z5n`Q|e=F;(oP6@_yS)#uq|Lv0KkDk5Sr*av_U?Pr9Qp0YoAtCUQ`N`9} zCpYjZH!v_&>Nph4InF+R9f$*QD<~NYRn$D&{;m7_vdW&nv#)Htc>FzgkFdn=yIRse zj!nOp)Grm9bCI?E5wuLa#~~o|{OrPIixCEZ(%6mzKi6&h7!dwA;_bJ6Z{OaUxAsu_ znawM$?{d6JbGF~G^>*2hdG)pD9Ix&3`)U)sU^iIzPc4UnIqTi$)uB4bo^y-ruYG6Z zx1ZeqE1^LD_1zU_X7-$OzI+p@&c4X?|JBCByKc9}em}qlj;+Q$ph~Ozu#Y-8$RL@^ zfuXUWu~p9??`>1^Rw+^K8y8Zl|_TcyPHeJa3m$UBuPuAF|8;{$+pKxZ~ z1uiNk^nP9-awZ&SVmV$}^Wmixib(}We_wvvnAvS} zB>s2lhSgPDSX3PstlaH*Z`Rt|f3K*D%Vqhl3iq7RJRRbLC-WE%7QT}Wu4)0932VS` zEYUUiu$A-MwL?$q{!Q{;?#KQw)Bn!Cc6$1{%l@F! zyU|8W!Q$NGX8-G`f&DlB&k?)0UALTjEbHQLulJM<5MuGG$lkQ~^II?buV)`u-85V) zt$OC5H^>l1mLmU#2NvJ^G;N(=Ng5n&m&9KDywh%0`n1aa|8w>48{d7+UbZ)9-)X_sX)`m;Jm{`l}P<7aZYpA@9X+v;4bi{D#FR>aHydGYt@8(W|Rp zW^0??Isey>#Jg{s)>W$zc2CCNClS#*>Nd}>|0el&ZRpumnfkN!jsIoc(W(Bl`h9J= zyyceNe~bK^9@kiY`vNN1PNXw7J+86)^+gt(IHAO+xCOU2%irh;mELpsNbs+y>s6+o z?x_eqxbuD4?e6?vNw}Dmg$I{}z*Y-@GjUGf{7z@2_`I-@PKcd&~5*(YcjnLKQgXAy&l5^Rx7E*Voozq&vEsUS7caegah-9BL?iF*vWUa#$A4;0Jw1K1 z?|!ROr>1L*8?*aEQr`(*#-_)2Y}S3@f`&6V6$yBFC;YhX{pQQ|{a-%wWnDcGXR|6j z>h#moK9j@OZ2tSt`e6BX@4HfFpWiTlUiumwYYqzMSvmSX|6y718`*ag?lWDEF}Rg{ z!(DD+=GIeY@82-~+bIM{UFv4 zal(@=plU=u&I-~@gT@<&h@QcZubtms{YkAm#?JR5N4zXE?uS#Qk^AxI$8K+z-uC03 zpT*k!U$bJ={j2=U!Qu2Nw&8)r{qqdJ`eBBEBCk@v;QErvvco^*PaDp;v23Dkxy$!G z=7I-$LZ#PS_nu$beQT=LjZ@uy8@S%FRhmHZ?I*{E2Nv>uMzzRIH%68qj+(7i&82nE znC;!Cay`vmxVkuIchON1?jpk+IUI8S|HXes)+|UN17&y>HHw-BIhkT%(H~CWhVY zJqBys>4QrBq9rfYQJgZtDdFR)QU_-~8xhiN`b3`? z_X&T!=l`r5Al-pUR+P}WOCGU$Vw9R@# z98|hlUV>yAc#wNIJ1p+|UinY?_Q&Lv${e)!$|T^FRctc$#AXTP)m z>Z%yS=e}~YKCX?muIqcBzLo1~?zGjpcUFaMo%7yY7LpnjK#e7z)=aRUVT6Mm_nLc~ z&RW^po~ygD=d3nQ=KUMxK$!0n=PonnEzHR=8qgr)Bx83X8vFn(4-`vFW z=VPCh?{PcI_3h}(ziW&4&PrXa{6-g&PE~ar3Stf|Si^@>`kfGM^vzSroBvRL_9=@M zrmLb(9-DXJ^sTGs=I+{WUi)k7UF*`oFB5DFEBLMVdw0Lco(D;yxOzBk2i}Cf&OP8g z{}xyH_lUK=Ygd_l`w@3-N!3%6Y3JTW{(G3m@Z+}sbGPzOo8IZZZEP;yJ*{}lW*ca` zT7a?Xu~S2ZG^z{B8~vxP*>*Vo=NYrS{~wPPf`%5av%O1Qn-!+J*`(Y*GQ+(7TX9B> z*KW0MhYYKue-=GGl{5cFAtar61vNa_p<)^-4haQFd?`#=%#?rT|3S9>h8MT(o^>GW z?A?yX;r%yH@4BiVy|p3q@(;K0d5`{O+F#2Hi|5OWJAcn^A;0-yVK!c{(;DZqaP(P< zLX#jYVP6uesC*}6oqZ+c_NLFrKkV>(+V$hVB%DpZw1$EmW9fyKHn_17J8O$YEQUB4){!>LScVcsyZ~wHi?D=J3 zD{Fox1YNWBi`sYYTxI^Q+RbIbCHMWZ?_Zf`w`qCkx(R!K%ifKIMOPwY(_^0I&6bcb zfttTy4YyCB;+q8%h2Pxfjb0S{^6G|Zwlx9M*J#IX%zf^+JO7o^@5kbwb8h=9FWq`M z{A*6`cbN;VvyNRm~Z;etX$=McLV|%RjP!gPDAT;&eDl8fxzWjPpUu`poebIc=+QdeGViw!`lqkkXuUrs zAzv>_@OrmhZ}#mCi@$9vD_wQm_c<%n9IPb?L!%PMnV6mT*8NLZw)b;xO~C4ld%61c z-`%i>X*`*wiHzr&*7F_lrz<99tlByF_?@^sllF+SOY&bw$RsTb9kQgtVFt zyc1KfxOdmR;Vq zoe}+9-S%;tj>Y{*o4MB}f9Bd-pFZ>c-jWnkF>QQeyTN?`m}ML(yAN!WwSGHu{l3lC>Ss4gt~P6Vm$&=Y)i({xN^=}0@4B`# zuJm=l?p>w@Pj!P#TaR#G%iXsAdd{ZKch71-72y0G6OYcm^Gzr^H9Y6%opWd3w$ znqFlpeE%7^jmN;mu>@3CunBF3MhvXMAmR%eeaikk{bv2L`s{rDsJz=rSqklISFY1m zzqlewb#>&*MOW8E9Gp5uBVBs?`wd@jm)+Qvdpq}I+uCi1*BXarKR%T>=jzItu@Ak1 zOx6dQUR|>X)~spe5RegPI&vGDk71rYDjc!1a`j$|@|C>*t2%q*H=SZV#OluZ{*~CR z-4{@R&-ZoI&LXVm%m6sQOb?Sx% z(1xHx8fcj9@tH7$qfl6lMxe=~G(J&l)Hp{(M2cI(0}JDGIgqhha6&;LG>n;8j;B5g z*ofLShee@6!>AKLr3I}*;e=G->*KmWK!w-d$!57u^W?Gbt5+&*;V>_+Q!_p%Wcd2=4MsD+1P${b@=)B*JkJM z%LMIW`TIzG|A}RHQ{n|~tYu<3zI*EYUeq#crsxdAs*-|x#dzgMxCKgRCo6XD%Yr$w&`T#TP8x}5VipL^z(UW=4`ed_7-_`F>bU*6aM zw@$u&W*YC`4~O}$Epp|aZCkx^N{?q4V2je!C67-|arXDs=U`}K19+c%rf`&C<}orz^^J@)&} z=Kizu?eBxO+q}KC_4d+pLNe)g7GVi@)PC*PYh%De%Ac{j|V^W>wk93R=rqw zP)GIKjeWJ%uWxT(Z~OgDv1`=wCb8atKi_WW|Ml3bq&w%a@&3QxZr5E&TJATuXwUMG zcW>{h+{`ckH8PB0`6boP+#?-=*H(w?XW!hE`Y8J1^_?;@`tkej+^c*pYro6>*25O{ z-N{Ebo-&H5`FM0&!9yqQ_iG7Z~Z_Vz;F z>-0;YWy-a`UM{!md3|$p`iq*~R)O}N;d7IIiZA{9u6)07uUXgymu~SJ<@amfPT&7$ zX>8$9(U1904z6b97Q3-2_4FG5`F0EU=HA=0^KSkBzh$R1m$&R&-?>vpreD_jTA$so zjN6-1y)XTH-}m6ho#OLbkM&C5jxE1CwPb(MSKhgsWv$D;h#yQ5Fll=1(B#fiC#GQW z?`Bgva_uvLk@4^Ooo+Yo6&&WRQ(2UEPUOy<6-&(R)6dCV*0``qMCP zm|@I_T+AD(EtpukYW2$5hM8A3W-Yo`a@qHv`sJk?h2!gfrfy-&j+88vu~_l%bLsWi z^z7^Fw!XT$ntgKjSC4`ioqbEV-)}rF_s>SnLeFD~)h*E3AotjgYfW8zaqmqLne6%h zKD684SQELKOKyYBj7{I~Ro~uvJudtC{QA0>e9ped78Q*R;tCeeT%ffd*jbG|oEcx{ z)=gVyeQWiz4NZY}kJg=;Vd#2`{VMZ3gTyBOkgvi&Q&Qzige|Uanqys_7qgP9cb9JX zx|kPcrczOjn@`1PBn0?AI5dmtroxn~d!pL&T9#kD^84-f`K2!|99*w7H%Rp0Hqb^j z>mzr!crDcqx~r3abyaAcobGbzsiwKNOd?zxk0;2RGKG{*yZU5;UvF@)g`8>Dlp|R%ejg5!2*gElK;K*e+I zGT+(H^yi&e9<V)0ArBzpD0H&8_^c zH$JQ8%$k4lue<4l($C(kQ+EZ3Y&r6_W$LO6=^m-MTmHSfyLaE#b|j`b3VwC2?Jm9WSub|ik+ZXZ9O^yOy<@`u14U6~ zPfkoM+`RjNX3=rka+jD1@1K`9PA@N5Sa_uOUH6h#+jna&h<7{g_*u5_h~U4{v$IV1 zrr&9svyzkqsY(a5}_F1QnO_l0ACv7wF{QQ4k)a&!Iyg|iKP&y|si}hEOWbQ?EW#81B{Xp-{H=W9bSNRH@%VvztT$NibYI*6?r^1KXcgikRF8q7pd)qnQ@I?xb^jIp3=gy8=e@?J`@{SH^!8s+R@046z z<}-)$U)R69A@Oj>Id9$d=NGL07?W@_x!>08<#V^wd%s-rzLbnmzUOjyP5v)K3na)EB)SjJ5?e|?>v5A|Nr-n`sSqjS9Y#BKXumb0`ZGK*S+@% zzjpY$^YMeRK0P~xJnH2BH9OdGyx`)63>$z;Kt>h;jZ#MQqSNe}@6umi%-uOL+fF3p zLsUet#G3zwpsf~bGY?}(cAZ|ky` z`i3t8Z>(N$qt~Z*&-Z)P7aP19zuhgr|JIo~*ZH7F#N~gxFYc?`oqHR!{P6u=!LQ-J zC8XKJR4u|TEWdE3caio6&(>*NVIr$EzHralT{w4pK*nRY*KCt(GnUn9w@iCD|No!o zE83+uO3l@O)5)`Cjr2m9KnF>QSB7RbK?+L`gf8sWb`>gA{`Ke8mH!GKruRypmE9(J zpa1RbU&^nG&snNJ%1e6sy!Wo(i$i&f&b9vg`}_BSQ@#IsYyNyZF4(#(>($|(dON~a zJb7jEJ2UaWq+QJp{uf*1<_b6N{pNh!S#i>C#|7~ri8ToezwVmN?iQcDtLg8JXKs4G zySce!MAxuAU+`<$?`7I(Qyl}Bz~?dulpIQWrOJm$gS(%O5?%g#@*E8g_~vHX7t zpT6oV-dJ$pEC8FUf>T>Pdq zHn^SEoDr}<>UPY|u8!ZF1#gxxou6OzN>e^-=j>gg75XzCc!jh0FYf0u5ZSh4_G8!O zs&;`23k36|9?sHf2u@gF5VrX0p;=A*;d%$yr>~Q7zoAnXwd>$UHy-UB1zQ8T*LWvR zcS>fRn&{hjnp1s_faRMFhq?Bw{r+U)sf`Dm?0qj37TLe{|5o)>wuou4Mu{1LdL{BCJ@V`%o2%}mL)Wrt>I z*FN~YqMI+#SA3#K)$%OIf;EC~n%VjFKFF?2E%n=B^>*TAe|y`jtGH_Y?{lBjyCSM? zajkq!-&SpJp;a(Fy-}3J*r}?k{|NFk5^`8Hn z2dDo1cz^CeQ_!Q|R@1Mt$69plRS>tHf6kuu{jLcP&IN0I|c(CJf zA2+XUjIH;7``7EH<-Uk}Re$AcaN^XR8d=`z7S}w2SgltcO3e*dW&0xhKH*5>n|&G` zfe#+!^@&;UJn;EYQ!=ZEROSl7GO5N@8%#H5E?LPGb9VNcOp$Hh+#AbtwAVg}xE)*( zb>sXU(@R00cS`?1`fggi9LsU8cdwQIo(&Vvsc~`lnR->9rZn$2mn&(%rCc*QmK3Ddymz!Vpw)NI< z*JaIplm74EuI2|p$~Jd-4=$=-^?udF9a2}0+}loe6bT}ui)nAsyp20zbQ3o`Dw+Qby@o!u^d0x@p#dk z`R~$Z-?Q1MR{h5A_0E0Ohx>Y)l6#x<-z=JcZJ|NL;>lajrs!UEop2*{i(YI>k@@BB zxo3)5ih>#*Sg7-B&qZ1#ps<@ov5^dv)gkw@u=l` zRV(7Q>^sgSy><1^P$?I4O`qi}d)n)I1#gSUyq@E+eC4@KO^-u>= zHW^8F-VS-NI*6-t?TUkiZ+bUw(YxAvHRD-|eL4TOUjh}0zx)!T9=*7payuwv$pnMKD^Z2b$+`ZE zziiR(EbUDG{`C6(e_QuE-tbhPE8_Y5{rdX9*>4^#HF{(rv2vxf#InmxRl7S=y}h(7 z!sgF5&wrQg@;a?e>Y&V>3%U}PvoqElSW*1^+{-t0FKkveJ$}FM_c{6N&*#_MmE1hi zxoY9s&km`|NzsMP$*ebaRW3aDa6#siU0(7mcC+e^%a;F`-OT#=Mc~rVkb3hqOSx{J ziYiz$A##76M-G>L>18+8)9rFqEBLKM->@%@EP1?dUF>c(y=U?1-UT(U*KT+F(%l)d zcE`cO4S919|5_K6Th%)+JaXQK?&4peE&J|Y{;7A_rqf)($K2xHp32Stzq^b32W<^` zUi7GFR`^2;-o_Yl1&ecEm3{t0!Vo;(aN{hK)Y+8>R&DsTj_aq%DxHmW%ik5OmkxjH zrLAL8_xtVkS`YK;Z*R7Qtv7HnU+bNtDk!u1{@&{E-;_THHNQ-#{(irH|NqRg8z;^u z%nRvXYWOJP^_s}dX;1X)e|oR-b-&N;wy*Br&*v92tAg%4h)ClyH~kg4u;fwYl3W$; zzR=y_r{89Ii^^o%uL@iHs(#x1bH7AOv@Pb@R2JQNbCkDlt5NTyp1+lQPZ_=VEP8w2 zpHJTM-&hkj*=?74Ia}fu>**z2w@(EXteN$wsQ$}E_vUp!-D}NXgtM{B*KDwNe|+!H zOV>z_K2xP%JD<S=P6+HKJ=jT;6piTBOEoNTlcru6KVBtC0ASSNU+K5<*N(cszjoa0mX^srvf0gCjqTD#X-_ek{XZUc z|GV@1-|zRy>HfbfS3QW(zIgtl{>~?pwp?2t_~BK%o9D4@lQ{Z9CpnoWHvc-gD>MGl z`TtveV-Iki3a|O`u-)!U^xmq{H}72LFNcKNXSe(IonP1U+k80C@o&=Aba9t$?8k-G z{l18obNx|FV{*;jtDlp z`EIpb?j!$4p;ZpbW|wy=#yqMDeIAw=uxj?al`Y3Y!(*rJ$Y{LIWo26QYuD>_+8^RP zS&v6;WQzEkVz;L6<)x+Gwe=y_lER}hS&!d(zAg8*Tm7#2S@%PZTfR}hca*p9yzTcp z9eJ0guTtgiYySM@~pG=-^{rAgd<+)a+U2~tz zpYBqy=0mt@;;|jGbza3>_$gDi*;e-agW`(Qy4zhs(rqHWMYpX~+hAAEB^_+aTHVaX z>t)(qzuqKUX7&8eRBMsGtXs4b>6bIc=aK)fxaDI`V*wS4W6W;u>abKXrEg&=f>Eh%2kR~D~JZ0ii3^^R67;5EPY9Tu7 zSl_mggf$0NY><|2U0eU>$49#v0R}VH{JsDG?|l9;F`bABIb!y)=2bxqCh6zqFnyky zQn2Qq)|qR)ix15@#e1UU@v+{-{N;1Pq7H6!Gtu(6=zAr|wAFl;eojboVe{j^-|yeQ z9^|{Vc4~cq!}N&95vNz&%R1gC%dNXoXxqPEUthZmz4knQZh1l2;x*jd3hKVIo;)dXydRMqbZ2ZPvdTtm5UYwXmVi@r+lcfa5FBJYJ$m)m3c!XttgGhHhu z`4y}w_BS{1S-#Y2dh+z?6Mf2`T3eLafO2xP1Jr|AQuOo`Yo3JI?s*p%yC46{6ZQV(v6`s(51W7A_}TpY7w0aw(^`8j zyx6i~*@D1_TbZ_R2%B_pm+80MH{29mH)kH!v^1HQWIydnp#$HXMOzs z6K7@`JC{4oSF~J_(vZLa7f;@LiKnl0 z-zz4^RS&Fgte4K;b8)&6r?&T^_mdT!+gz%?ymaATI>^62{5=bQ9yE!{Qo>E`oxukEEz{4pZ zGksz6(RJVzP|#SK#xm(H%i0ZgE7UeMExEDmg0ubBumc5`ea(Lgcqp!5^7wlua^X@p z=GXPFgl9W#dUtoXd&v0+-`BIO%k%E!+zRjAaAk#KuO82<_p6Q^om+nIy<$t|DihBCB_`AHi0$~Qz||9ipLfn%y`F3Ku|8Spi@rNdoB|prIPKZ+ zAmaB&(8)`mUw{S)HB5L9t*ZR|?B}k_TvHEaS!&O?l;PEy>^R#rJM6<1d#xVZClj1& z43^K|!TxoM=%ro>!$bW_*E^o4EPm{*WpVAOq^0J9YZ*6Ed=>ZGSxeoWw@Oq@CcgIT z)qgR)ygb7BZjrYRf{v~JQ@JwUq2}w=@O{=?J)$L9E?e!qwX%h;eYv|Rd3CX}#`MLT zxPPq+j9BxYb!wA`n9S?n%PK!V`{$PBsIdC|^asB^ZeOvn(&y$@E?*kb+IN2G^f;+& zTbV9@nHd_ePWl?_{xug^dymUipQ#rIP0{|_ytKBLx9@9Y@JfllvmEyGT>PH-VeXRN z6Jcz#)YoX5T(ex65ViPSbGN;fTh#Rfjm&?mJ5P&=$z%Hg&&B<=zsx(J z+<&*knEwi@jbxQQ$>hmeC~H;n;k1TK7)QyC#CFjex~$d9=a$Xl_cQrqA~AQ>@k3dW z(@F}~%;k2|QoFs)N$zTEsKKJYQ@7sv@@L26zRycJgsdZH9o)EW=~wNH@DGcUmk4g- zn!F`mN>NtYO!Xb8Nw_xu$A^a(KQH#2tX8+1t4Sn|?fK-Uw#C`18axzd zy<%9czv}cHog2Xd6_-5KfBqD4dgWgmx3g$zm}D;3r_#FDcX(^I$j+TCWhfi7p+isL z^O7Y^$!mk=v*(&~tWP!*u3a_zS*E=Hz8{ZXY}ud=>cJgdeIVxbrF74S)sHxCT;l69 zZHiYu1-j(={`&_%UhH;WY8^Cn<;A1Su^kupSWPcwbeeB?SHS3pYV*G7lUR=%UG~+L zHp`KSjhi32lXdNursTEZ*Af>$Y0g!*TlH^iUf+txOOuz{y;cedNK#rMEcY$)+IqWR z-`~I2-*>{}`OLf>%Rm3-um9m3Gh@z<*uO!J;>JzqoA;ehS(jSM*VekfmGyX4ytw_P zTr0I*21|;=%uB8w^{8ckapR=(@i_6y42~z09V|<))iPut&n7lF%oHq8{&%L=XLHon zteM=>XIM{Ye!trrV=OK+lUsdl=<2X%Zl7jxt2#};xJR$WEcbA4otd~q+qvnw!dv$T zFZVMQuba7h<*d?ocW%bq*ce^z|9|#NCbj+X>v%eL&fh+pdy>&6f4vvR;bI43HoWVf z&%K~5bNB0OYd^m(Y}{-gAHxy%qUw%@Z~eTT8_wLxC@6mF>ok3$zrp%%=X*QO&hUT1 zH}#WCx#Ph*8p*{Ex9_}g?e-3a{ZqF8di?6HD^GFhnX|pqz6zJv+meqU~Vm1+IDc=`LX@7!#~jay%Set77$ zQm*}s$m1vfG98SuoR|o{Z}+*lHm}fU~j) zH9uxDe)6HE_?+eOJ1-K8_cNV%7}r*Qwm0A#<6fuu@2eX>%$(81z|;y_D&%#92cZ|r z3J_!cWNJ}n+IDs-n_)Qf-ETM3=WnWb(Y5t_`JKY{okFtDUTKSG+v@aS-yjHDJ$NFp zv4*#=omV<-o!?e{%ZZEI%~H2leS4E>ey5;$Zuz}R&F7DOSp+$?1@s)9IHz&kKB?h!w6 z{ei`Mej5f3&~9*+Fcp-JCzgKTl(3#Ds$g+$jd`>)$hQ!)P*|Jd8Xj1@<`=Z?fR2?x!xnBxN?5}Ki_Q0P zP$yClCY`8aY +## What Supervision Means + +Supervision describes a dependency relationship between actors: the supervisor delegates tasks to subordinates and +therefore must respond to their failures. When a subordinate detects a failure +(i.e. throws an exception), it suspends itself and all its subordinates and +sends a message to its supervisor, signaling failure. Depending on the nature +of the work to be supervised and the nature of the failure, the supervisor has +a choice of the following four options: + + 1. Resume the subordinate, keeping its accumulated internal state + 2. Restart the subordinate, clearing out its accumulated internal state + 3. Stop the subordinate permanently + 4. Escalate the failure, thereby failing itself + +It is important to always view an actor as part of a supervision hierarchy, +which explains the existence of the fourth choice (as a supervisor also is +subordinate to another supervisor higher up) and has implications on the first +three: resuming an actor resumes all its subordinates, restarting an actor +entails restarting all its subordinates (but see below for more details), +similarly terminating an actor will also terminate all its subordinates. It +should be noted that the default behavior of the `preRestart` hook of the +`Actor` class is to terminate all its children before restarting, but +this hook can be overridden; the recursive restart applies to all children left +after this hook has been executed. + +Each supervisor is configured with a function translating all possible failure +causes (i.e. exceptions) into one of the four choices given above; notably, +this function does not take the failed actor’s identity as an input. It is +quite easy to come up with examples of structures where this might not seem +flexible enough, e.g. wishing for different strategies to be applied to +different subordinates. At this point it is vital to understand that +supervision is about forming a recursive fault handling structure. If you try +to do too much at one level, it will become hard to reason about, hence the +recommended way in this case is to add a level of supervision. + +Akka implements a specific form called “parental supervision”. Actors can only +be created by other actors—where the top-level actor is provided by the +library—and each created actor is supervised by its parent. This restriction +makes the formation of actor supervision hierarchies implicit and encourages +sound design decisions. It should be noted that this also guarantees that +actors cannot be orphaned or attached to supervisors from the outside, which +might otherwise catch them unawares. In addition, this yields a natural and +clean shutdown procedure for (sub-trees of) actor applications. + +@@@ warning + +Supervision related parent-child communication happens by special system +messages that have their own mailboxes separate from user messages. This +implies that supervision related events are not deterministically +ordered relative to ordinary messages. In general, the user cannot influence +the order of normal messages and failure notifications. For details and +example see the @ref:[Discussion: Message Ordering](general/message-delivery-reliability.md#message-ordering) section. + +@@@ + + +## The Top-Level Supervisors + +![guardians.png](general/guardians.png) + +An actor system will during its creation start at least three actors, shown in +the image above. For more information about the consequences for actor paths +see @ref:[Top-Level Scopes for Actor Paths](general/addressing.md#toplevel-paths). + + +### `/user`: The Guardian Actor + +The actor which is probably most interacted with is the parent of all +user-created actors, the guardian named `"/user"`. Actors created using +`system.actorOf()` are children of this actor. This means that when this +guardian terminates, all normal actors in the system will be shutdown, too. It +also means that this guardian’s supervisor strategy determines how the +top-level normal actors are supervised. Since Akka 2.1 it is possible to +configure this using the setting `akka.actor.guardian-supervisor-strategy`, +which takes the fully-qualified class-name of a +`SupervisorStrategyConfigurator`. When the guardian escalates a failure, +the root guardian’s response will be to terminate the guardian, which in effect +will shut down the whole actor system. + +### `/system`: The System Guardian + +This special guardian has been introduced in order to achieve an orderly +shut-down sequence where logging remains active while all normal actors +terminate, even though logging itself is implemented using actors. This is +realized by having the system guardian watch the user guardian and initiate its own +shut-down upon reception of the `Terminated` message. The top-level +system actors are supervised using a strategy which will restart indefinitely +upon all types of `Exception` except for +`ActorInitializationException` and `ActorKilledException`, which +will terminate the child in question. All other throwables are escalated, +which will shut down the whole actor system. + +### `/`: The Root Guardian + +The root guardian is the grand-parent of all so-called “top-level” actors and +supervises all the special actors mentioned in @ref:[Top-Level Scopes for Actor Paths](general/addressing.md#toplevel-paths) using the +`SupervisorStrategy.stoppingStrategy`, whose purpose is to terminate the +child upon any type of `Exception`. All other throwables will be +escalated … but to whom? Since every real actor has a supervisor, the +supervisor of the root guardian cannot be a real actor. And because this means +that it is “outside of the bubble”, it is called the “bubble-walker”. This is a +synthetic `ActorRef` which in effect stops its child upon the first sign +of trouble and sets the actor system’s `isTerminated` status to `true` as +soon as the root guardian is fully terminated (all children recursively +stopped). + + +## One-For-One Strategy vs. All-For-One Strategy + +There are two classes of supervision strategies which come with Akka: +`OneForOneStrategy` and `AllForOneStrategy`. Both are configured +with a mapping from exception type to supervision directive (see +[above](#supervision-directives)) and limits on how often a child is allowed to fail +before terminating it. The difference between them is that the former applies +the obtained directive only to the failed child, whereas the latter applies it +to all siblings as well. Normally, you should use the +`OneForOneStrategy`, which also is the default if none is specified +explicitly. + +The `AllForOneStrategy` is applicable in cases where the ensemble of +children has such tight dependencies among them, that a failure of one child +affects the function of the others, i.e. they are inextricably linked. Since a +restart does not clear out the mailbox, it often is best to terminate the children +upon failure and re-create them explicitly from the supervisor (by watching the +children’s lifecycle); otherwise you have to make sure that it is no problem +for any of the actors to receive a message which was queued before the restart +but processed afterwards. + +Normally stopping a child (i.e. not in response to a failure) will not +automatically terminate the other children in an all-for-one strategy; this can +be done by watching their lifecycle: if the `Terminated` message +is not handled by the supervisor, it will throw a `DeathPactException` +which (depending on its supervisor) will restart it, and the default +`preRestart` action will terminate all children. Of course this can be +handled explicitly as well. + +Please note that creating one-off actors from an all-for-one supervisor entails +that failures escalated by the temporary actor will affect all the permanent +ones. If this is not desired, install an intermediate supervisor; this can very +be done by declaring a router of size 1 for the worker, see +@ref:[Routing](routing.md). + + + + diff --git a/akka-docs/src/main/paradox/typed/fault-tolerance.md b/akka-docs/src/main/paradox/typed/fault-tolerance.md index 238c384180..b10c7fd586 100644 --- a/akka-docs/src/main/paradox/typed/fault-tolerance.md +++ b/akka-docs/src/main/paradox/typed/fault-tolerance.md @@ -32,7 +32,12 @@ with a fresh state that we know is valid. ## Supervision -In Akka this "somewhere else" is called supervision. Supervision allows you to declaratively describe what should happen when a certain type of exceptions are thrown inside an actor. To use supervision the actual Actor behavior is wrapped using `Behaviors.supervise`, for example to restart on `IllegalStateExceptions`: +In Akka this "somewhere else" is called supervision. Supervision allows you to declaratively describe what should happen when a certain type of exceptions are thrown inside an actor. + +To use supervision the actual Actor behavior is wrapped using `Behaviors.supervise`. Typically you would wrap the actor + with supervision in the parent when spawning it as a child. + +This example restarts the actor when it fails with an `IllegalStateException`: Scala @@ -140,6 +145,7 @@ Scala Java : @@snip [SupervisionCompileOnlyTest.java](/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/supervision/SupervisionCompileOnlyTest.java) { #restart-PreRestart-signal } + ## Bubble failures up through the hierarchy In some scenarios it may be useful to push the decision about what to do on a failure upwards in the Actor hierarchy diff --git a/akka-docs/src/test/java/jdocs/actor/typed/SharedMutableStateDocTest.java b/akka-docs/src/test/java/jdocs/actor/typed/SharedMutableStateDocTest.java new file mode 100644 index 0000000000..86341ec8d1 --- /dev/null +++ b/akka-docs/src/test/java/jdocs/actor/typed/SharedMutableStateDocTest.java @@ -0,0 +1,141 @@ +/* + * Copyright (C) 2009-2019 Lightbend Inc. + */ + +package jdocs.actor.typed; + +import akka.actor.typed.ActorRef; +import akka.actor.typed.Behavior; +import akka.actor.typed.javadsl.AbstractBehavior; +import akka.actor.typed.javadsl.ActorContext; +import akka.actor.typed.javadsl.Receive; +import akka.actor.typed.javadsl.AskPattern; + +import java.time.Duration; +import java.util.HashSet; +import java.util.Set; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.CompletionStage; + +interface SharedMutableStateDocTest { + + static CompletableFuture expensiveCalculation() { + throw new UnsupportedOperationException("just a sample signature"); + } + + class Query { + public final ActorRef replyTo; + + public Query(ActorRef replyTo) { + this.replyTo = replyTo; + } + } + + // #mutable-state + class MyActor extends AbstractBehavior { + + interface Command {} + + class Message implements Command { + public final ActorRef otherActor; + + public Message(ActorRef replyTo) { + this.otherActor = replyTo; + } + } + + class UpdateState implements Command { + public final String newState; + + public UpdateState(String newState) { + this.newState = newState; + } + } + + private final ActorContext context; + + private String state = ""; + private Set mySet = new HashSet<>(); + + public MyActor(ActorContext context) { + this.context = context; + } + + @Override + public Receive createReceive() { + return newReceiveBuilder() + .onMessage(Message.class, this::onMessage) + .onMessage(UpdateState.class, this::onUpdateState) + .build(); + } + + private Behavior onMessage(Message message) { + // Very bad: shared mutable object allows + // the other actor to mutate your own state, + // or worse, you might get weird race conditions + message.otherActor.tell(mySet); + + // Example of incorrect approach + // Very bad: shared mutable state will cause your + // application to break in weird ways + CompletableFuture.runAsync( + () -> { + state = "This will race"; + }); + + // Example of incorrect approach + // Very bad: shared mutable state will cause your + // application to break in weird ways + expensiveCalculation() + .whenComplete( + (result, failure) -> { + if (result != null) state = "new state: " + result; + }); + + // Example of correct approach + // Turn the future result into a message that is sent to + // self when future completes + CompletableFuture futureResult = expensiveCalculation(); + context.pipeToSelf( + futureResult, + (result, failure) -> { + if (result != null) return new UpdateState(result); + else throw new RuntimeException(failure); + }); + + // Another example of incorrect approach + // mutating actor state from ask future callback + CompletionStage response = + AskPattern.ask( + message.otherActor, + Query::new, + Duration.ofSeconds(3), + context.getSystem().scheduler()); + response.whenComplete( + (result, failure) -> { + if (result != null) state = "new state: " + result; + }); + + // use context.ask instead, turns the completion + // into a message sent to self + context.ask( + String.class, + message.otherActor, + Duration.ofSeconds(3), + Query::new, + (result, failure) -> { + if (result != null) return new UpdateState(result); + else throw new RuntimeException(failure); + }); + return this; + } + + private Behavior onUpdateState(UpdateState command) { + // safe as long as `newState` is immutable, if it is mutable we'd need to + // make a defensive copy + this.state = command.newState; + return this; + } + } + // #mutable-state +} diff --git a/akka-docs/src/test/java/jdocs/config/ConfigDoc.java b/akka-docs/src/test/java/jdocs/config/ConfigDoc.java deleted file mode 100644 index 3b8702fa15..0000000000 --- a/akka-docs/src/test/java/jdocs/config/ConfigDoc.java +++ /dev/null @@ -1,28 +0,0 @@ -/* - * Copyright (C) 2009-2019 Lightbend Inc. - */ - -package jdocs.config; - -import akka.actor.ActorSystem; -import com.typesafe.config.*; - -public class ConfigDoc { - public ActorSystem createConfiguredSystem() { - // #java-custom-config - // make a Config with just your special setting - Config myConfig = ConfigFactory.parseString("something=somethingElse"); - // load the normal config stack (system props, - // then application.conf, then reference.conf) - Config regularConfig = ConfigFactory.load(); - // override regular stack with myConfig - Config combined = myConfig.withFallback(regularConfig); - // put the result in between the overrides - // (system props) and defaults again - Config complete = ConfigFactory.load(combined); - // create ActorSystem - ActorSystem system = ActorSystem.create("myname", complete); - // #java-custom-config - return system; - } -} diff --git a/akka-docs/src/test/java/jdocs/config/ConfigDocTest.java b/akka-docs/src/test/java/jdocs/config/ConfigDocTest.java new file mode 100644 index 0000000000..9d10574caf --- /dev/null +++ b/akka-docs/src/test/java/jdocs/config/ConfigDocTest.java @@ -0,0 +1,70 @@ +/* + * Copyright (C) 2009-2019 Lightbend Inc. + */ + +package jdocs.config; + +// #imports +import akka.actor.typed.ActorSystem; +import akka.actor.typed.Behavior; +import akka.actor.typed.javadsl.Behaviors; +import com.typesafe.config.Config; +import com.typesafe.config.ConfigFactory; + +// #imports +import akka.actor.testkit.typed.javadsl.ActorTestKit; + +public class ConfigDocTest { + + private Behavior rootBehavior = Behaviors.empty(); + + public void customConfig() { + // #custom-config + Config customConf = ConfigFactory.parseString("akka.log-config-on-start = on"); + // ConfigFactory.load sandwiches customConfig between default reference + // config and default overrides, and then resolves it. + ActorSystem system = + ActorSystem.create(rootBehavior, "MySystem", ConfigFactory.load(customConf)); + // #custom-config + + ActorTestKit.shutdown(system); + } + + public void compileOnlyPrintConfig() { + // #dump-config + ActorSystem system = ActorSystem.create(rootBehavior, "MySystem"); + system.logConfiguration(); + // #dump-config + } + + public void compileOnlySeparateApps() { + // #separate-apps + Config config = ConfigFactory.load(); + ActorSystem app1 = + ActorSystem.create(rootBehavior, "MyApp1", config.getConfig("myapp1").withFallback(config)); + ActorSystem app2 = + ActorSystem.create( + rootBehavior, + "MyApp2", + config.getConfig("myapp2").withOnlyPath("akka").withFallback(config)); + // #separate-apps + } + + public ActorSystem createConfiguredSystem() { + // #custom-config-2 + // make a Config with just your special setting + Config myConfig = ConfigFactory.parseString("something=somethingElse"); + // load the normal config stack (system props, + // then application.conf, then reference.conf) + Config regularConfig = ConfigFactory.load(); + // override regular stack with myConfig + Config combined = myConfig.withFallback(regularConfig); + // put the result in between the overrides + // (system props) and defaults again + Config complete = ConfigFactory.load(combined); + // create ActorSystem + ActorSystem system = ActorSystem.create(rootBehavior, "myname", complete); + // #custom-config-2 + return system; + } +} diff --git a/akka-docs/src/test/scala/docs/actor/typed/SharedMutableStateDocSpec.scala b/akka-docs/src/test/scala/docs/actor/typed/SharedMutableStateDocSpec.scala new file mode 100644 index 0000000000..7c5dd7c548 --- /dev/null +++ b/akka-docs/src/test/scala/docs/actor/typed/SharedMutableStateDocSpec.scala @@ -0,0 +1,94 @@ +/* + * Copyright (C) 2009-2019 Lightbend Inc. + */ + +package docs.actor.typed + +import akka.actor.typed.scaladsl._ +import akka.actor.typed.{ ActorRef, Behavior } +import akka.util.Timeout + +import scala.collection.mutable +import scala.concurrent.Future +import scala.concurrent.duration._ +import scala.util.{ Failure, Success } + +class SharedMutableStateDocSpec { + + def expensiveCalculation(): Future[String] = ??? + + object MyActor { + trait Command + case class Message(msg: String, replyTo: ActorRef[Any]) extends Command + case class UpdateState(newState: String) extends Command + + case class Query(replyTo: ActorRef[String]) + + def apply(): Behavior[Command] = Behaviors.setup { context => + new MyActor(context) + } + } + //#mutable-state + class MyActor(context: ActorContext[MyActor.Command]) extends AbstractBehavior[MyActor.Command] { + import MyActor._ + + var state = "" + val mySet = mutable.Set[String]() + + def onMessage(cmd: MyActor.Command) = cmd match { + case Message(text, otherActor) => + // Very bad: shared mutable object allows + // the other actor to mutate your own state, + // or worse, you might get weird race conditions + otherActor ! mySet + + implicit val ec = context.executionContext + + // Example of incorrect approach + // Very bad: shared mutable state will cause your + // application to break in weird ways + Future { state = "This will race" } + + // Example of incorrect approach + // Very bad: shared mutable state will cause your + // application to break in weird ways + expensiveCalculation().foreach { result => + state = s"new state: $result" + } + + // Example of correct approach + // Turn the future result into a message that is sent to + // self when future completes + val futureResult = expensiveCalculation() + context.pipeToSelf(futureResult) { + case Success(result) => UpdateState(result) + case Failure(ex) => throw ex + } + + // Another example of incorrect approach + // mutating actor state from ask future callback + import akka.actor.typed.scaladsl.AskPattern._ + implicit val timeout = Timeout(5.seconds) // needed for `ask` below + implicit val scheduler = context.system.scheduler + val future: Future[String] = otherActor.ask(Query) + future.foreach { result => + state = result + } + + // use context.ask instead, turns the completion + // into a message sent to self + context.ask(otherActor, Query) { + case Success(result) => UpdateState(result) + case Failure(ex) => throw ex + } + this + + case UpdateState(newState) => + // safe as long as `newState` is immutable, if it is mutable we'd need to + // make a defensive copy + state = newState + this + } + } + //#mutable-state +} diff --git a/akka-docs/src/test/scala/docs/config/ConfigDocSpec.scala b/akka-docs/src/test/scala/docs/config/ConfigDocSpec.scala index 9a14ab3e3f..b6ca5b5234 100644 --- a/akka-docs/src/test/scala/docs/config/ConfigDocSpec.scala +++ b/akka-docs/src/test/scala/docs/config/ConfigDocSpec.scala @@ -4,33 +4,63 @@ package docs.config +import akka.actor.testkit.typed.scaladsl.ActorTestKit +import akka.actor.typed.scaladsl.Behaviors import org.scalatest.WordSpec import org.scalatest.Matchers -import akka.testkit.TestKit //#imports -import akka.actor.ActorSystem +import akka.actor.typed.ActorSystem import com.typesafe.config.ConfigFactory //#imports class ConfigDocSpec extends WordSpec with Matchers { + val rootBehavior = Behaviors.empty[String] "programmatically configure ActorSystem" in { + //#custom-config val customConf = ConfigFactory.parseString(""" - akka.actor.deployment { - /my-service { - router = round-robin-pool - nr-of-instances = 3 - } - } - """) + akka.log-config-on-start = on + """) // ConfigFactory.load sandwiches customConfig between default reference // config and default overrides, and then resolves it. - val system = ActorSystem("MySystem", ConfigFactory.load(customConf)) + val system = ActorSystem(rootBehavior, "MySystem", ConfigFactory.load(customConf)) //#custom-config - TestKit.shutdownActorSystem(system) + ActorTestKit.shutdown(system) + } + + def compileOnlyPrintConfig(): Unit = { + // #dump-config + val system = ActorSystem(rootBehavior, "MySystem") + system.logConfiguration() + // #dump-config + } + + def compileOnlySeparateApps(): Unit = { + // #separate-apps + val config = ConfigFactory.load() + val app1 = ActorSystem(rootBehavior, "MyApp1", config.getConfig("myapp1").withFallback(config)) + val app2 = ActorSystem(rootBehavior, "MyApp2", config.getConfig("myapp2").withOnlyPath("akka").withFallback(config)) + // #separate-apps + } + + def moreCustomConfig(): Unit = { + // #custom-config-2 + // make a Config with just your special setting + val myConfig = ConfigFactory.parseString("something=somethingElse"); + // load the normal config stack (system props, + // then application.conf, then reference.conf) + val regularConfig = ConfigFactory.load(); + // override regular stack with myConfig + val combined = myConfig.withFallback(regularConfig); + // put the result in between the overrides + // (system props) and defaults again + val complete = ConfigFactory.load(combined); + // create ActorSystem + val system = ActorSystem(rootBehavior, "myname", complete); + // #custom-config-2 } "deployment section" in { @@ -76,7 +106,7 @@ class ConfigDocSpec extends WordSpec with Matchers { } #//#deployment-section """) - val system = ActorSystem("MySystem", conf) - TestKit.shutdownActorSystem(system) + val system = ActorSystem(rootBehavior, "MySystem", conf) + ActorTestKit.shutdown(system) } }