Fixups & docs for Akka 2.6's default dispatcher (#9480)

Fixups & docs for Akka 2.6's default dispatcher

core/play/src/main/resources/play/reference-overrides.conf

@@ -17,15 +17,6 @@ akka {
   # can't handle requests since the Akka system is shutdown only.
   jvm-exit-on-fatal-error = true
 
-  actor {
-    default-dispatcher = {
-      fork-join-executor {
-        # Settings this to 1 instead of 3 seems to improve performance.
-        parallelism-factor = 1.0
-      }
-    }
-  }
-
   # Tell akka to use Slf4jLogger and filter
   loglevel = DEBUG
   loggers = ["akka.event.slf4j.Slf4jLogger"]

documentation/manual/releases/release28/migration28/Migration28.md

@@ -92,6 +92,14 @@ Many changes have been made to Play's internal APIs. These APIs are used interna
 
 This section lists changes and deprecations in configurations.
 
+### Dropped the overrides for `akka.actor.default-dispatcher.fork-join-executor`
+
+The overrides that Play had under `akka.actor.default-dispatcher.fork-join-executor` have been dropped in favour of using Akka's new-and-improved defaults.
+
+See the section related to [changes in the default dispatch][akka-migration-guide-default-dispatcher] in Akka's migration guide for more details.
+
+[akka-migration-guide-default-dispatcher]: https://doc.akka.io/docs/akka/2.6/project/migration-guide-2.5.x-2.6.x.html#default-dispatcher-size
+
 ### Configuration loading changes
 
 Until Play 2.7, when loading configuration, Play was not considering the default [Java System Properties](https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html) if the user provides some properties. Now, System Properties are always considered, meaning that you can reference them in your `application.conf` file even if you are also defining custom properties. For example, when [[embedding Play|ScalaEmbeddingPlayAkkaHttp]] like the code below, both `userProperties` and System Properties are used:

documentation/manual/working/commonGuide/configuration/ThreadPools.md

@@ -46,21 +46,19 @@ or using [`CompletionStage`](https://docs.oracle.com/javase/8/docs/api/java/util
 
 @[http-execution-context](code/detailedtopics/httpec/MyController.java)
 
-This execution context connects directly to the Application's `ActorSystem` and uses the [default dispatcher](https://doc.akka.io/docs/akka/2.5/dispatchers.html?language=scala).
+This execution context connects directly to the Application's `ActorSystem` and uses Akka's [default dispatcher][akka-default-dispatcher].
 
 ### Configuring the default thread pool
 
-The default thread pool can be configured using standard Akka configuration in `application.conf` under the `akka` namespace. Here is default configuration for Play's thread pool:
+The default thread pool can be configured using standard Akka configuration in `application.conf` under the `akka` namespace.
 
-@[default-config](code/ThreadPools.scala)
+If you want to configure the default dispatcher, use another dispatcher, or define a new dispatcher to use, see the [Types of dispatchers][akka-dispatcher-types] section of Akka's reference documentation for full details.
 
-This configuration instructs Akka to create 1 thread per available processor, with a maximum of 24 threads in the pool.
+The full configuration options available to you can be found in the [Configuration][akka-default-config] section.
 
-You can also try the default Akka configuration:
-
-@[akka-default-config](code/ThreadPools.scala)
-
-The full configuration options available to you can be found [here](https://doc.akka.io/docs/akka/2.5.3/java/general/configuration.html#listing-of-the-reference-configuration).
+[akka-default-config]:     https://doc.akka.io/docs/akka/2.6/general/configuration.html#listing-of-the-reference-configuration
+[akka-default-dispatcher]: https://doc.akka.io/docs/akka/2.6/dispatchers.html#default-dispatcher
+[akka-dispatcher-types]:   https://doc.akka.io/docs/akka/2.6/dispatchers.html#types-of-dispatchers
 
 ## Using other thread pools
 

documentation/manual/working/commonGuide/configuration/code/ThreadPools.scala

@@ -27,67 +27,6 @@ class ThreadPoolsSpec extends PlaySpecification {
       contentAsString(controller.someAsyncAction(FakeRequest())) must startWith("The answer is 42")
     }
 
-    "have a global configuration" in {
-      val config      = """#default-config
-        akka {
-          actor {
-            default-dispatcher {
-              fork-join-executor {
-                # Settings this to 1 instead of 3 seems to improve performance.
-                parallelism-factor = 1.0
-
-                # @richdougherty: Not sure why this is set below the Akka
-                # default.
-                parallelism-max = 24
-
-                # Setting this to LIFO changes the fork-join-executor
-                # to use a stack discipline for task scheduling. This usually
-                # improves throughput at the cost of possibly increasing
-                # latency and risking task starvation (which should be rare).
-                task-peeking-mode = LIFO
-              }
-            }
-          }
-        }
-      #default-config """
-      val parsed      = ConfigFactory.parseString(config)
-      val actorSystem = ActorSystem("test", parsed.getConfig("akka"))
-      actorSystem.terminate()
-      success
-    }
-
-    "use akka default thread pool configuration" in {
-      val config      = """#akka-default-config
-        akka {
-          actor {
-            default-dispatcher {
-              # This will be used if you have set "executor = "fork-join-executor""
-              fork-join-executor {
-                # Min number of threads to cap factor-based parallelism number to
-                parallelism-min = 8
-
-                # The parallelism factor is used to determine thread pool size using the
-                # following formula: ceil(available processors * factor). Resulting size
-                # is then bounded by the parallelism-min and parallelism-max values.
-                parallelism-factor = 3.0
-
-                # Max number of threads to cap factor-based parallelism number to
-                parallelism-max = 64
-
-                # Setting to "FIFO" to use queue like peeking mode which "poll" or "LIFO" to use stack
-                # like peeking mode which "pop".
-                task-peeking-mode = "FIFO"
-              }
-            }
-          }
-        }
-      #akka-default-config """
-      val parsed      = ConfigFactory.parseString(config)
-      val actorSystem = ActorSystem("test", parsed.getConfig("akka"))
-      actorSystem.terminate()
-      success
-    }
-
     "allow configuring a custom thread pool" in runningWithConfig(
       """#my-context-config
         my-context {