diff --git a/akka-docs/src/main/paradox/dispatchers.md b/akka-docs/src/main/paradox/dispatchers.md index 208ed77699..0715b9a2f5 100644 --- a/akka-docs/src/main/paradox/dispatchers.md +++ b/akka-docs/src/main/paradox/dispatchers.md @@ -27,32 +27,7 @@ An Akka `MessageDispatcher` is what makes Akka Actors "tick", it is the engine o All `MessageDispatcher` implementations are also an `ExecutionContext`, which means that they can be used to execute arbitrary code, for instance @ref:[Futures](futures.md). -## Default dispatcher - -Every `ActorSystem` will have a default dispatcher that will be used in case nothing else is configured for an `Actor`. -The default dispatcher can be configured, and is by default a `Dispatcher` with the specified `default-executor`. -If an ActorSystem is created with an ExecutionContext passed in, this ExecutionContext will be used as the default executor for all -dispatchers in this ActorSystem. If no ExecutionContext is given, it will fallback to the executor specified in -`akka.actor.default-dispatcher.default-executor.fallback`. By default this is a "fork-join-executor", which -gives excellent performance in most cases. - -## Internal dispatcher - -To protect the internal Actors that is spawned by the various Akka modules, a separate internal dispatcher is used by default. -The internal dispatcher can be tuned in a fine grained way with the setting `akka.actor.internal-dispatcher`, it can also -be replaced by another dispatcher by making `akka.actor.internal-dispatcher` an @ref[alias](#dispatcher-aliases). - - - -## Looking up a Dispatcher - -Dispatchers implement the `ExecutionContext` interface and can thus be used to run `Future` invocations etc. - -Scala -: @@snip [DispatcherDocSpec.scala](/akka-docs/src/test/scala/docs/dispatcher/DispatcherDocSpec.scala) { #lookup } - -Java -: @@snip [DispatcherDocTest.java](/akka-docs/src/test/java/jdocs/dispatcher/DispatcherDocTest.java) { #lookup } +For full details on how to work with dispatchers see the @ref:[main dispatcher docs](typed/dispatchers.md#types-of-dispatchers). ## Setting the dispatcher for an Actor @@ -115,46 +90,6 @@ where you'd use periods to denote sub-sections, like this: `"foo.bar.my-dispatch @@@ -## Types of dispatchers - -There are 3 different types of message dispatchers: - -* **Dispatcher** - - This is an event-based dispatcher that binds a set of Actors to a thread - pool. It is the default dispatcher used if one is not specified. - - * Sharability: Unlimited - * Mailboxes: Any, creates one per Actor - * Use cases: Default dispatcher, Bulkheading - * Driven by: `java.util.concurrent.ExecutorService`. - Specify using "executor" using "fork-join-executor", "thread-pool-executor" or the FQCN of - an `akka.dispatcher.ExecutorServiceConfigurator`. - -* **PinnedDispatcher** - - This dispatcher dedicates a unique thread for each actor using it; i.e. - each actor will have its own thread pool with only one thread in the pool. - - * Sharability: None - * Mailboxes: Any, creates one per Actor - * Use cases: Bulkheading - * Driven by: Any `akka.dispatch.ThreadPoolExecutorConfigurator`. - By default a "thread-pool-executor". - -* **CallingThreadDispatcher** - - This dispatcher runs invocations on the current thread only. This - dispatcher does not create any new threads, but it can be used from - different threads concurrently for the same actor. - See @ref:[CallingThreadDispatcher](testing.md#callingthreaddispatcher) - for details and restrictions. - - * Sharability: Unlimited - * Mailboxes: Any, creates one per Actor per Thread (on demand) - * Use cases: Debugging and testing - * Driven by: The calling thread (duh) - ### More dispatcher configuration examples Configuring a dispatcher with fixed thread pool size, e.g. for actors that perform blocking IO: @@ -203,19 +138,6 @@ is used for `PinnedDispatcher` to keep resource usage down in case of idle actor thread all the time you need to add `thread-pool-executor.allow-core-timeout=off` to the configuration of the `PinnedDispatcher`. -## Dispatcher aliases - -When a dispatcher is looked up, and the given setting contains a string rather than a dispatcher config block, -the lookup will treat it as an alias, and follow that string to an alternate location for a dispatcher config. -If the dispatcher config is referenced both through an alias and through the absolute path only one dispatcher will -be used and shared among the two ids. - -Example: configuring `internal-dispatcher` to be an alias for `default-dispatcher`: - -``` -akka.actor.internal-dispatcher = akka.actor.default-dispatcher -``` - ## Blocking Needs Careful Management In some cases it is unavoidable to do blocking operations, i.e. to put a thread @@ -428,7 +350,7 @@ on which DBMS is deployed on what hardware. Configuring thread pools is a task best delegated to Akka, configure it in `application.conf` and instantiate through an -@ref:[`ActorSystem`](#dispatcher-lookup) +@ref:[`ActorSystem`](typed/dispatchers.md#dispatcher-lookup) @@@ diff --git a/akka-docs/src/main/paradox/typed/actor-lifecycle.md b/akka-docs/src/main/paradox/typed/actor-lifecycle.md index e29ff8d47f..84fac4ea67 100644 --- a/akka-docs/src/main/paradox/typed/actor-lifecycle.md +++ b/akka-docs/src/main/paradox/typed/actor-lifecycle.md @@ -85,7 +85,7 @@ Java : @@snip [IntroSpec.scala](/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/IntroTest.java) { #hello-world-main } To specify a dispatcher when spawning an actor use @apidoc[DispatcherSelector]. If not specified, the actor will -use the default dispatcher, see @ref:[Default dispatcher](../dispatchers.md#default-dispatcher) for details. +use the default dispatcher, see @ref:[Default dispatcher](dispatchers.md#default-dispatcher) for details. Scala : @@snip [IntroSpec.scala](/akka-actor-typed-tests/src/test/scala/docs/akka/typed/IntroSpec.scala) { #hello-world-main-with-dispatchers } diff --git a/akka-docs/src/main/paradox/typed/dispatchers.md b/akka-docs/src/main/paradox/typed/dispatchers.md index 3bf92a132c..564472cb37 100644 --- a/akka-docs/src/main/paradox/typed/dispatchers.md +++ b/akka-docs/src/main/paradox/typed/dispatchers.md @@ -16,6 +16,32 @@ An Akka `MessageDispatcher` is what makes Akka Actors "tick", it is the engine o All `MessageDispatcher` implementations are also an @scala[`ExecutionContext`]@java[`Executor`], which means that they can be used to execute arbitrary code, for instance @ref:[Futures](../futures.md). +## Default dispatcher + +Every `ActorSystem` will have a default dispatcher that will be used in case nothing else is configured for an `Actor`. +The default dispatcher can be configured, and is by default a `Dispatcher` with the specified `default-executor`. +If an ActorSystem is created with an ExecutionContext passed in, this ExecutionContext will be used as the default executor for all +dispatchers in this ActorSystem. If no ExecutionContext is given, it will fallback to the executor specified in +`akka.actor.default-dispatcher.default-executor.fallback`. By default this is a "fork-join-executor", which +gives excellent performance in most cases. + +## Internal dispatcher + +To protect the internal Actors that is spawned by the various Akka modules, a separate internal dispatcher is used by default. +The internal dispatcher can be tuned in a fine grained way with the setting `akka.actor.internal-dispatcher`, it can also +be replaced by another dispatcher by making `akka.actor.internal-dispatcher` an @ref[alias](#dispatcher-aliases). + + +## Looking up a Dispatcher + +Dispatchers implement the `ExecutionContext` interface and can thus be used to run `Future` invocations etc. + +Scala +: @@snip [DispatcherDocSpec.scala](/akka-docs/src/test/scala/docs/dispatcher/DispatcherDocSpec.scala) { #lookup } + +Java +: @@snip [DispatcherDocTest.java](/akka-docs/src/test/java/jdocs/dispatcher/DispatcherDocTest.java) { #lookup } + ## Selecting a dispatcher A default dispatcher is used for all actors that are spawned without specifying a custom dispatcher. @@ -44,4 +70,64 @@ Scala Java : @@snip [DispatcherDocSpec.scala](/akka-actor-typed-tests/src/test/scala/docs/akka/typed/DispatchersDocSpec.scala) { #config } -For full details on how to configure custom dispatchers see the @ref:[untyped docs](../dispatchers.md#types-of-dispatchers). +## Types of dispatchers + +There are 3 different types of message dispatchers: + +* **Dispatcher** + + This is an event-based dispatcher that binds a set of Actors to a thread + pool. It is the default dispatcher used if one is not specified. + + * Sharability: Unlimited + * Mailboxes: Any, creates one per Actor + * Use cases: Default dispatcher, Bulkheading + * Driven by: `java.util.concurrent.ExecutorService`. + Specify using "executor" using "fork-join-executor", "thread-pool-executor" or the FQCN of + an `akka.dispatcher.ExecutorServiceConfigurator`. + +* **PinnedDispatcher** + + This dispatcher dedicates a unique thread for each actor using it; i.e. + each actor will have its own thread pool with only one thread in the pool. + + * Sharability: None + * Mailboxes: Any, creates one per Actor + * Use cases: Bulkheading + * Driven by: Any `akka.dispatch.ThreadPoolExecutorConfigurator`. + By default a "thread-pool-executor". + +* **CallingThreadDispatcher** + + This dispatcher runs invocations on the current thread only. This + dispatcher does not create any new threads, but it can be used from + different threads concurrently for the same actor. + See @ref:[CallingThreadDispatcher](../testing.md#callingthreaddispatcher) + for details and restrictions. + + * Sharability: Unlimited + * Mailboxes: Any, creates one per Actor per Thread (on demand) + * Use cases: Debugging and testing + * Driven by: The calling thread (duh) + +## Dispatcher aliases + +When a dispatcher is looked up, and the given setting contains a string rather than a dispatcher config block, +the lookup will treat it as an alias, and follow that string to an alternate location for a dispatcher config. +If the dispatcher config is referenced both through an alias and through the absolute path only one dispatcher will +be used and shared among the two ids. + +Example: configuring `internal-dispatcher` to be an alias for `default-dispatcher`: + +``` +akka.actor.internal-dispatcher = akka.actor.default-dispatcher +``` + +## Blocking Needs Careful Management + +In some cases it is unavoidable to do blocking operations, i.e. to put a thread +to sleep for an indeterminate time, waiting for an external event to occur. +Examples are legacy RDBMS drivers or messaging APIs, and the underlying reason +is typically that (network) I/O occurs under the covers. + +How to deal with this is currently documented as part of the [Classic Dispatcher](../dispatchers.md#blocking-needs-careful-management)