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 <helena@users.noreply.github.com>

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

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)
-
-<!--same config text for Scala & Java-->
-@@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`:
-
-<!--same config text for Scala & Java-->
-@@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`.

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

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.
+<!--same config text for Scala & Java-->
+@@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)
+
+<!--same config text for Scala & Java-->
+@@snip [DispatcherDocSpec.scala](/akka-docs/src/test/scala/docs/dispatcher/DispatcherDocSpec.scala) {#my-thread-pool-dispatcher-config }
+
+Configuring a `PinnedDispatcher`:
+
+<!--same config text for Scala & Java-->
+@@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`.

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)
 
 @@@