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
|
||||
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 }
|
||||
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)
|
||||
|
||||
@@@
|
||||
|
||||
|
|
|
|||
|
|
@ -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 }
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
||||
<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
|
||||
|
||||
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)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue