From 808520992033c79c1348a092d004fc01fc65dbbc Mon Sep 17 00:00:00 2001 From: Patrik Nordwall Date: Thu, 29 Aug 2019 17:50:57 +0200 Subject: [PATCH] Remove CallingThreadDispatcher from main dispatchers doc, #27223 (#27593) * It is described thoroughly in the classic testing docs, and it's not something we should promote too much. * Also move more dispatcher examples to main Dispatchers docs * Small adjustment of ToC * review suggestions Co-Authored-By: Helena Edelson --- .../docs/akka/typed/DispatchersDocSpec.scala | 2 +- akka-docs/src/main/paradox/dispatchers.md | 53 ++--------------- akka-docs/src/main/paradox/testing.md | 3 + .../src/main/paradox/typed/dispatchers.md | 58 +++++++++++++++---- akka-docs/src/main/paradox/typed/index.md | 7 ++- 5 files changed, 59 insertions(+), 64 deletions(-) diff --git a/akka-actor-typed-tests/src/test/scala/docs/akka/typed/DispatchersDocSpec.scala b/akka-actor-typed-tests/src/test/scala/docs/akka/typed/DispatchersDocSpec.scala index 329329cf70..5c2c343fdb 100644 --- a/akka-actor-typed-tests/src/test/scala/docs/akka/typed/DispatchersDocSpec.scala +++ b/akka-actor-typed-tests/src/test/scala/docs/akka/typed/DispatchersDocSpec.scala @@ -48,8 +48,8 @@ object DispatchersDocSpec { context.spawn(yourBehavior, "DefaultDispatcher") context.spawn(yourBehavior, "ExplicitDefaultDispatcher", DispatcherSelector.default()) context.spawn(yourBehavior, "BlockingDispatcher", DispatcherSelector.blocking()) - context.spawn(yourBehavior, "DispatcherFromConfig", DispatcherSelector.fromConfig("your-dispatcher")) context.spawn(yourBehavior, "ParentDispatcher", DispatcherSelector.sameAsParent()) + context.spawn(yourBehavior, "DispatcherFromConfig", DispatcherSelector.fromConfig("your-dispatcher")) //#spawn-dispatcher Behaviors.same diff --git a/akka-docs/src/main/paradox/dispatchers.md b/akka-docs/src/main/paradox/dispatchers.md index c5f4bda99c..1b5303c15a 100644 --- a/akka-docs/src/main/paradox/dispatchers.md +++ b/akka-docs/src/main/paradox/dispatchers.md @@ -7,10 +7,12 @@ known as Akka Typed. Akka Classic is still fully supported and existing applicat the classic APIs. It is also possible to use Akka Typed together with classic actors within the same ActorSystem, see @ref[coexistence](typed/coexisting.md). For new projects we recommend using the new Actor APIs. -For the new API see @ref[dispatchers](typed/dispatchers.md). +For the new API see @ref[Dispatchers](typed/dispatchers.md). @@@ +For more details on advanced dispatcher config and options, see @ref[Dispatchers](typed/dispatchers.md). + ## Dependency Dispatchers are part of core Akka, which means that they are part of the akka-actor dependency: @@ -61,7 +63,7 @@ You can read more about it in the JDK's [ThreadPoolExecutor documentation](https @@@ -For more options, see the default-dispatcher section of the @ref:[configuration](general/configuration.md). +For more options, see @ref[Dispatchers](typed/dispatchers.md) and the `default-dispatcher` section of the @ref:[configuration](general/configuration.md). Then you create the actor as usual and define the dispatcher in the deployment configuration. @@ -93,50 +95,3 @@ where you'd use periods to denote sub-sections, like this: `"foo.bar.my-dispatch @@@ -### More dispatcher configuration examples - -Configuring a dispatcher with fixed thread pool size, e.g. for actors that perform blocking IO: - -@@snip [DispatcherDocSpec.scala](/akka-docs/src/test/scala/docs/dispatcher/DispatcherDocSpec.scala) { #fixed-pool-size-dispatcher-config } - -And then using it: - -Scala -: @@snip [DispatcherDocSpec.scala](/akka-docs/src/test/scala/docs/dispatcher/DispatcherDocSpec.scala) { #defining-fixed-pool-size-dispatcher } - -Java -: @@snip [DispatcherDocTest.java](/akka-docs/src/test/java/jdocs/dispatcher/DispatcherDocTest.java) { #defining-fixed-pool-size-dispatcher } - -Another example that uses the thread pool based on the number of cores (e.g. for CPU bound tasks) - - -@@snip [DispatcherDocSpec.scala](/akka-docs/src/test/scala/docs/dispatcher/DispatcherDocSpec.scala) {#my-thread-pool-dispatcher-config } - -A different kind of dispatcher that uses an affinity pool may increase throughput in cases where there is relatively small -number of actors that maintain some internal state. The affinity pool tries its best to ensure that an actor is always -scheduled to run on the same thread. This actor to thread pinning aims to decrease CPU cache misses which can result -in significant throughput improvement. - -@@snip [DispatcherDocSpec.scala](/akka-docs/src/test/scala/docs/dispatcher/DispatcherDocSpec.scala) { #affinity-pool-dispatcher-config } - -Configuring a `PinnedDispatcher`: - - -@@snip [DispatcherDocSpec.scala](/akka-docs/src/test/scala/docs/dispatcher/DispatcherDocSpec.scala) {#my-pinned-dispatcher-config } - -And then using it: - -Scala -: @@snip [DispatcherDocSpec.scala](/akka-docs/src/test/scala/docs/dispatcher/DispatcherDocSpec.scala) { #defining-pinned-dispatcher } - -Java -: @@snip [DispatcherDocTest.java](/akka-docs/src/test/java/jdocs/dispatcher/DispatcherDocTest.java) { #defining-pinned-dispatcher } - -Note that `thread-pool-executor` configuration as per the above `my-thread-pool-dispatcher` example is -NOT applicable. This is because every actor will have its own thread pool when using `PinnedDispatcher`, -and that pool will have only one thread. - -Note that it's not guaranteed that the *same* thread is used over time, since the core pool timeout -is used for `PinnedDispatcher` to keep resource usage down in case of idle actors. To use the same -thread all the time you need to add `thread-pool-executor.allow-core-timeout=off` to the -configuration of the `PinnedDispatcher`. diff --git a/akka-docs/src/main/paradox/testing.md b/akka-docs/src/main/paradox/testing.md index 587522b8da..d26ddc8e52 100644 --- a/akka-docs/src/main/paradox/testing.md +++ b/akka-docs/src/main/paradox/testing.md @@ -580,6 +580,9 @@ responsible for the Actor creation, but @scala[the]@java[using `TestProbe` or ha ## CallingThreadDispatcher +The `CallingThreadDispatcher` runs invocations on the current thread only. This +dispatcher does not create any new threads. + It is possible to use the `CallingThreadDispatcher` in unit testing, as described above, but originally it was conceived in order to allow contiguous stack traces to be generated in case of an error. As this special dispatcher diff --git a/akka-docs/src/main/paradox/typed/dispatchers.md b/akka-docs/src/main/paradox/typed/dispatchers.md index 10927ee25d..102c10a96a 100644 --- a/akka-docs/src/main/paradox/typed/dispatchers.md +++ b/akka-docs/src/main/paradox/typed/dispatchers.md @@ -67,7 +67,7 @@ The final example shows how to load a custom dispatcher from configuration and r ## Types of dispatchers -There are 3 different types of message dispatchers: +There are 2 different types of message dispatchers: * **Dispatcher** @@ -92,18 +92,29 @@ There are 3 different types of message dispatchers: * Driven by: Any `akka.dispatch.ThreadPoolExecutorConfigurator`. By default a "thread-pool-executor". -* **CallingThreadDispatcher** +Here is an example configuration of a Fork Join Pool dispatcher: - 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. + +@@snip [DispatcherDocSpec.scala](/akka-docs/src/test/scala/docs/dispatcher/DispatcherDocSpec.scala) { #my-dispatcher-config } - * Sharability: Unlimited - * Mailboxes: Any, creates one per Actor per Thread (on demand) - * Use cases: Debugging and testing - * Driven by: The calling thread (duh) +For more configuration options, see the @ref:[More dispatcher configuration examples](#more-dispatcher-configuration-examples) +section and the `default-dispatcher` section of the @ref:[configuration](../general/configuration.md). + +@@@ note + +The `parallelism-max` for the `fork-join-executor` does not set the upper bound on the total number of threads +allocated by the ForkJoinPool. It is a setting specifically talking about the number of *hot* +threads the pool will keep running in order to reduce the latency of handling a new incoming task. +You can read more about parallelism in the JDK's [ForkJoinPool documentation](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ForkJoinPool.html). + +@@@ + +@@@ note + +The `thread-pool-executor` dispatcher is implemented using by a `java.util.concurrent.ThreadPoolExecutor`. +You can read more about it in the JDK's [ThreadPoolExecutor documentation](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ThreadPoolExecutor.html). + +@@@ ## Dispatcher aliases @@ -330,3 +341,28 @@ it in `application.conf` and instantiate through an @ref:[`ActorSystem`](#dispatcher-lookup) @@@ + +## More dispatcher configuration examples + +Configuring a dispatcher with fixed thread pool size, e.g. for actors that perform blocking IO: + +@@snip [DispatcherDocSpec.scala](/akka-docs/src/test/scala/docs/dispatcher/DispatcherDocSpec.scala) { #fixed-pool-size-dispatcher-config } + +Another example that uses the thread pool based on the number of cores (e.g. for CPU bound tasks) + + +@@snip [DispatcherDocSpec.scala](/akka-docs/src/test/scala/docs/dispatcher/DispatcherDocSpec.scala) {#my-thread-pool-dispatcher-config } + +Configuring a `PinnedDispatcher`: + + +@@snip [DispatcherDocSpec.scala](/akka-docs/src/test/scala/docs/dispatcher/DispatcherDocSpec.scala) {#my-pinned-dispatcher-config } + +Note that `thread-pool-executor` configuration as per the above `my-thread-pool-dispatcher` example is +NOT applicable. This is because every actor will have its own thread pool when using `PinnedDispatcher`, +and that pool will have only one thread. + +Note that it's not guaranteed that the *same* thread is used over time, since the core pool timeout +is used for `PinnedDispatcher` to keep resource usage down in case of idle actors. To use the same +thread all the time you need to add `thread-pool-executor.allow-core-timeout=off` to the +configuration of the `PinnedDispatcher`. diff --git a/akka-docs/src/main/paradox/typed/index.md b/akka-docs/src/main/paradox/typed/index.md index 00c8a626d3..0c01188108 100644 --- a/akka-docs/src/main/paradox/typed/index.md +++ b/akka-docs/src/main/paradox/typed/index.md @@ -5,9 +5,7 @@ @@@ index * [actors](actors.md) -* [dispatchers](dispatchers.md) -* [mailboxes](mailboxes.md) -* [coexisting](coexisting.md) + * [actor-lifecycle](actor-lifecycle.md) * [interaction patterns](interaction-patterns.md) * [fault-tolerance](fault-tolerance.md) @@ -16,7 +14,10 @@ * [stash](stash.md) * [stream](stream.md) * [fsm](fsm.md) +* [dispatchers](dispatchers.md) +* [mailboxes](mailboxes.md) * [testing](testing.md) +* [coexisting](coexisting.md) * [style-guide](style-guide.md) @@@