Add close on ActorSystem

Author: mdedetrich

actor-testkit-typed/src/main/scala/org/apache/pekko/actor/testkit/typed/internal/ActorSystemStub.scala

@@ -113,6 +113,10 @@ import com.typesafe.config.{ Config, ConfigFactory }
   override def terminate(): Unit = terminationPromise.trySuccess(Done)
   override def whenTerminated: Future[Done] = terminationPromise.future
   override def getWhenTerminated: CompletionStage[Done] = whenTerminated.asJava
+  override def close(): Unit = {
+    terminate()
+    Await.result(whenTerminated, scala.concurrent.duration.Duration.Inf)
+  }
   override val startTime: Long = System.currentTimeMillis()
   override def uptime: Long = System.currentTimeMillis() - startTime
   override def threadFactory: java.util.concurrent.ThreadFactory = new ThreadFactory {

actor-tests/src/test/scala/org/apache/pekko/actor/ActorSystemSpec.scala

@@ -263,7 +263,7 @@ class ActorSystemSpec extends PekkoSpec(ActorSystemSpec.config) with ImplicitSen
 
     "throw RejectedExecutionException when shutdown" in {
       val system2 = ActorSystem("RejectedExecution-1", PekkoSpec.testConf)
-      Await.ready(system2.terminate(), 10.seconds)
+      system2.close()
 
       intercept[RejectedExecutionException] {
         system2.registerOnTermination { println("IF YOU SEE THIS THEN THERE'S A BUG HERE") }

actor-tests/src/test/scala/org/apache/pekko/dispatch/DispatcherShutdownSpec.scala

@@ -45,7 +45,7 @@ class DispatcherShutdownSpec extends AnyWordSpec with Matchers {
       val system = ActorSystem("DispatcherShutdownSpec")
       threadCount should be > 0
 
-      Await.ready(system.terminate(), 1.second)
+      system.close()
       Await.ready(Future(pekko.Done)(system.dispatcher), 1.second)
 
       TestKit.awaitCond(threadCount == 0, 3.second)

actor-typed/src/main/scala/org/apache/pekko/actor/typed/ActorSystem.scala

@@ -13,7 +13,7 @@
 
 package org.apache.pekko.actor.typed
 
-import java.util.concurrent.{ CompletionStage, ThreadFactory }
+import java.util.concurrent.{ CompletionStage, ThreadFactory, TimeoutException }
 
 import scala.concurrent.{ ExecutionContextExecutor, Future }
 
@@ -42,7 +42,7 @@ import com.typesafe.config.{ Config, ConfigFactory }
  * Not for user extension.
  */
 @DoNotInherit
-abstract class ActorSystem[-T] extends ActorRef[T] with Extensions with ClassicActorSystemProvider {
+abstract class ActorSystem[-T] extends ActorRef[T] with Extensions with ClassicActorSystemProvider with AutoCloseable {
   this: InternalRecipientRef[T] =>
 
   /**
@@ -147,6 +147,26 @@ abstract class ActorSystem[-T] extends ActorRef[T] with Extensions with ClassicA
    */
   def getWhenTerminated: CompletionStage[Done]
 
+  /**
+   * Terminates this actor system by running [[pekko.actor.CoordinatedShutdown]] with reason
+   * [[pekko.actor.CoordinatedShutdown.ActorSystemTerminateReason]]. This method will block
+   * until either the actor system is terminated or
+   * `pekko.coordinated-shutdown.close-actor-system-timeout` timeout duration is
+   * passed, in which case a [[TimeoutException]] is thrown.
+   *
+   * If `pekko.coordinated-shutdown.run-by-actor-system-terminate` is configured to `off`
+   * it will not run `CoordinatedShutdown`, but the `ActorSystem` and its actors
+   * will still be terminated.
+   *
+   * This will stop the guardian actor, which in turn
+   * will recursively stop all its child actors, and finally the system guardian
+   * (below which the logging actors reside) and then execute all registered
+   * termination handlers (see [[pekko.actor.ActorSystem.registerOnTermination]]).
+   * @since 1.3.0
+   */
+  @throws(classOf[TimeoutException])
+  override def close(): Unit
+
   /**
    * The deadLetter address is a destination that will accept (and discard)
    * every message sent to it.

actor-typed/src/main/scala/org/apache/pekko/actor/typed/internal/adapter/ActorSystemAdapter.scala

@@ -122,6 +122,8 @@ import org.slf4j.{ Logger, LoggerFactory }
   override lazy val getWhenTerminated: CompletionStage[pekko.Done] =
     whenTerminated.asJava
 
+  override def close(): Unit = system.close()
+
   override def systemActorOf[U](behavior: Behavior[U], name: String, props: Props): ActorRef[U] = {
     val ref = system.systemActorOf(
       PropsAdapter(

actor/src/main/mima-filters/1.3.x.backwards.excludes/actorsystem-close.excludes

@@ -0,0 +1,21 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# Add close to ActorSystem
+ProblemFilters.exclude[InheritedNewAbstractMethodProblem]("org.apache.pekko.actor.ActorSystem.close")
+ProblemFilters.exclude[InheritedNewAbstractMethodProblem]("org.apache.pekko.actor.ExtendedActorSystem.close")
+ProblemFilters.exclude[ReversedMissingMethodProblem]("org.apache.pekko.actor.ActorSystem.close")

actor/src/main/resources/reference.conf

@@ -1244,6 +1244,9 @@ pekko {
     # Terminate the ActorSystem in the last phase actor-system-terminate.
     terminate-actor-system = on
 
+    # The timeout that will be used when calling .close on an ActorSystem
+    close-actor-system-timeout = 60 s
+
     # Exit the JVM (System.exit(0)) in the last phase actor-system-terminate
     # if this is set to 'on'. It is done after termination of the
     # ActorSystem if terminate-actor-system=on, otherwise it is done

actor/src/main/scala/org/apache/pekko/actor/ActorSystem.scala

@@ -20,7 +20,7 @@ import java.util.concurrent.atomic.AtomicReference
 
 import scala.annotation.tailrec
 import scala.collection.immutable
-import scala.concurrent.{ ExecutionContext, ExecutionContextExecutor, Future, Promise }
+import scala.concurrent.{ Await, ExecutionContext, ExecutionContextExecutor, Future, Promise }
 import scala.concurrent.blocking
 import scala.concurrent.duration.Duration
 import scala.jdk.CollectionConverters._
@@ -524,7 +524,7 @@ object ActorSystem {
  * extending [[pekko.actor.ExtendedActorSystem]] instead, but beware that you
  * are completely on your own in that case!
  */
-abstract class ActorSystem extends ActorRefFactory with ClassicActorSystemProvider {
+abstract class ActorSystem extends ActorRefFactory with ClassicActorSystemProvider with AutoCloseable {
   import ActorSystem._
 
   /**
@@ -677,6 +677,26 @@ abstract class ActorSystem extends ActorRefFactory with ClassicActorSystemProvid
    */
   def terminate(): Future[Terminated]
 
+  /**
+   * Terminates this actor system by running [[CoordinatedShutdown]] with reason
+   * [[CoordinatedShutdown.ActorSystemTerminateReason]]. This method will block
+   * until either the actor system is terminated or
+   * `pekko.coordinated-shutdown.close-actor-system-timeout` timeout duration is
+   * passed, in which case a [[TimeoutException]] is thrown.
+   *
+   * If `pekko.coordinated-shutdown.run-by-actor-system-terminate` is configured to `off`
+   * it will not run `CoordinatedShutdown`, but the `ActorSystem` and its actors
+   * will still be terminated.
+   *
+   * This will stop the guardian actor, which in turn
+   * will recursively stop all its child actors, and finally the system guardian
+   * (below which the logging actors reside) and then execute all registered
+   * termination handlers (see [[ActorSystem#registerOnTermination]]).
+   * @since 1.3.0
+   */
+  @throws(classOf[TimeoutException])
+  override def close(): Unit
+
   /**
    * Returns a Future which will be completed after the ActorSystem has been terminated
    * and termination hooks have been executed. If you registered any callback with
@@ -1080,6 +1100,13 @@ private[pekko] class ActorSystemImpl(
     whenTerminated
   }
 
+  override def close(): Unit = {
+    terminate()
+    val duration = Duration(settings.config.getDuration("coordinated-shutdown.close-actor-system-timeout").toMillis,
+      TimeUnit.MILLISECONDS)
+    Await.result(whenTerminated, duration)
+  }
+
   override private[pekko] def finalTerminate(): Unit = {
     terminating = true
     // these actions are idempotent

bench-jmh/src/main/scala/org/apache/pekko/actor/ActorBenchmark.scala

@@ -15,9 +15,6 @@ package org.apache.pekko.actor
 
 import java.util.concurrent.TimeUnit
 
-import scala.concurrent.Await
-import scala.concurrent.duration._
-
 import BenchmarkActors._
 import org.openjdk.jmh.annotations._
 
@@ -100,10 +97,8 @@ class ActorBenchmark {
   }
 
   @TearDown(Level.Trial)
-  def shutdown(): Unit = {
-    system.terminate()
-    Await.ready(system.whenTerminated, 15.seconds)
-  }
+  def shutdown(): Unit =
+    system.close()
 
   @Benchmark
   @OperationsPerInvocation(totalMessages)

bench-jmh/src/main/scala/org/apache/pekko/actor/ActorCreationBenchmark.scala

@@ -15,9 +15,6 @@ package org.apache.pekko.actor
 
 import java.util.concurrent.TimeUnit
 
-import scala.concurrent.Await
-import scala.concurrent.duration._
-
 import org.openjdk.jmh.annotations._
 
 /*
@@ -46,10 +43,8 @@ class ActorCreationBenchmark {
   }
 
   @TearDown(Level.Trial)
-  def shutdown(): Unit = {
-    system.terminate()
-    Await.ready(system.whenTerminated, 15.seconds)
-  }
+  def shutdown(): Unit =
+    system.close()
 
   @Benchmark
   @OutputTimeUnit(TimeUnit.MICROSECONDS)