Merge pull request #27494 from akka/dispatchersDoc
Move generic dispatcher docs from Classic
This commit is contained in:
Patrik Nordwall
GitHub
commit
f808dd0f30
3 changed files with 90 additions and 82 deletions
|
|
@ -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
|
All `MessageDispatcher` implementations are also an `ExecutionContext`, which means that they can be used
|
||||||
to execute arbitrary code, for instance @ref:[Futures](futures.md).
|
to execute arbitrary code, for instance @ref:[Futures](futures.md).
|
||||||
|
|
||||||
## Default dispatcher
|
For full details on how to work with dispatchers see the @ref:[main dispatcher docs](typed/dispatchers.md#types-of-dispatchers).
|
||||||
|
|
||||||
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).
|
|
||||||
|
|
||||||
|
|
||||||
<a id="dispatcher-lookup"></a>
|
|
||||||
## 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 }
|
|
||||||
|
|
||||||
## Setting the dispatcher for an Actor
|
## 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
|
### More dispatcher configuration examples
|
||||||
|
|
||||||
Configuring a dispatcher with fixed thread pool size, e.g. for actors that perform blocking IO:
|
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
|
thread all the time you need to add `thread-pool-executor.allow-core-timeout=off` to the
|
||||||
configuration of the `PinnedDispatcher`.
|
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
|
## Blocking Needs Careful Management
|
||||||
|
|
||||||
In some cases it is unavoidable to do blocking operations, i.e. to put a thread
|
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
|
Configuring thread pools is a task best delegated to Akka, configure
|
||||||
it in `application.conf` and instantiate through an
|
it in `application.conf` and instantiate through an
|
||||||
@ref:[`ActorSystem`](#dispatcher-lookup)
|
@ref:[`ActorSystem`](typed/dispatchers.md#dispatcher-lookup)
|
||||||
|
|
||||||
@@@
|
@@@
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -85,7 +85,7 @@ Java
|
||||||
: @@snip [IntroSpec.scala](/akka-actor-typed-tests/src/test/java/jdocs/akka/typed/IntroTest.java) { #hello-world-main }
|
: @@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
|
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
|
Scala
|
||||||
: @@snip [IntroSpec.scala](/akka-actor-typed-tests/src/test/scala/docs/akka/typed/IntroSpec.scala) { #hello-world-main-with-dispatchers }
|
: @@snip [IntroSpec.scala](/akka-actor-typed-tests/src/test/scala/docs/akka/typed/IntroSpec.scala) { #hello-world-main-with-dispatchers }
|
||||||
|
|
|
||||||
|
|
@ -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
|
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).
|
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).
|
||||||
|
|
||||||
|
<a id="dispatcher-lookup"></a>
|
||||||
|
## 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
|
## Selecting a dispatcher
|
||||||
|
|
||||||
A default dispatcher is used for all actors that are spawned without specifying a custom dispatcher.
|
A default dispatcher is used for all actors that are spawned without specifying a custom dispatcher.
|
||||||
|
|
@ -44,4 +70,64 @@ Scala
|
||||||
Java
|
Java
|
||||||
: @@snip [DispatcherDocSpec.scala](/akka-actor-typed-tests/src/test/scala/docs/akka/typed/DispatchersDocSpec.scala) { #config }
|
: @@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)
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue