add CoordinatedShutdown, #21537

* CoordinatedShutdown that can run tasks for configured phases in order (DAG)
* coordinate handover/shutdown of singleton with cluster exiting/shutdown
* phase config obj with depends-on list
* integrate graceful leaving of sharding in coordinated shutdown
* add timeout and recover
* add some missing artery ports to tests
* leave via CoordinatedShutdown.run
* optionally exit-jvm in last phase
* run via jvm shutdown hook
* send ExitingConfirmed to leader before shutdown of Exiting
  to not have to wait for failure detector to mark it as
  unreachable before removing
* the unreachable signal is still kept as a safe guard if
  message is lost or leader dies
* PhaseClusterExiting vs MemberExited in ClusterSingletonManager
* terminate ActorSystem when cluster shutdown (via Down)
* add more predefined and custom phases
* reference documentation
* migration guide
* problem when the leader order was sys2, sys1, sys3,
  then sys3 could not perform it's duties and move Leving sys1 to
  Exiting because it was observing sys1 as unreachable
* exclude Leaving with exitingConfirmed from convergence condidtion

akka-docs/rst/scala/code/docs/actor/ActorDocSpec.scala

@@ -20,6 +20,8 @@ import akka.testkit._
 import akka.util._
 import scala.concurrent.duration._
 import scala.concurrent.Await
+import akka.Done
+import akka.actor.CoordinatedShutdown
 
 //#my-actor
 class MyActor extends Actor {
@@ -631,4 +633,30 @@ class ActorDocSpec extends AkkaSpec("""
     })
   }
 
+  "using CoordinatedShutdown" in {
+    val someActor = system.actorOf(Props(classOf[Replier], this))
+    //#coordinated-shutdown-addTask
+    CoordinatedShutdown(system).addTask(
+      CoordinatedShutdown.PhaseBeforeServiceUnbind, "someTaskName") { () =>
+      import akka.pattern.ask
+      import system.dispatcher
+      implicit val timeout = Timeout(5.seconds)
+      (someActor ? "stop").map(_ => Done)
+    }
+    //#coordinated-shutdown-addTask
+
+    //#coordinated-shutdown-jvm-hook
+    CoordinatedShutdown(system).addJvmShutdownHook { () =>
+      println("custom JVM shutdown hook...")
+    }
+    //#coordinated-shutdown-jvm-hook
+
+    // don't run this
+    def dummy(): Unit = {
+      //#coordinated-shutdown-run
+      val done: Future[Done] = CoordinatedShutdown(system).run()
+      //#coordinated-shutdown-run
+    }
+  }
+
 }