Add close on ActorSystem

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/java/org/apache/pekko/actor/ActorSystemTest.java

@@ -15,6 +15,7 @@
 
 import static java.util.concurrent.TimeUnit.SECONDS;
 import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
 
 import java.util.concurrent.CompletionStage;
 import org.apache.pekko.testkit.PekkoJUnitActorSystemResource;
@@ -47,4 +48,14 @@ public void testGetWhenTerminated() throws Exception {
   public void testGetWhenTerminatedWithoutTermination() {
     assertFalse(system.getWhenTerminated().toCompletableFuture().isDone());
   }
+
+  @Test
+  public void testTryWithResources() throws Exception {
+    ActorSystem system = null;
+    try (ActorSystem actorSystem = ActorSystem.create()) {
+      system = actorSystem;
+    }
+    final CompletionStage<Terminated> cs = system.getWhenTerminated();
+    assertTrue(cs.toCompletableFuture().isDone());
+  }
 }

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

@@ -19,6 +19,7 @@ import java.util.concurrent.atomic.AtomicInteger
 import scala.annotation.nowarn
 import scala.concurrent.{ Await, Future }
 import scala.concurrent.duration._
+import scala.util.Using
 
 import org.scalatestplus.scalacheck.ScalaCheckPropertyChecks
 
@@ -263,7 +264,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") }
@@ -334,6 +335,20 @@ class ActorSystemSpec extends PekkoSpec(ActorSystemSpec.config) with ImplicitSen
       }
     }
 
+    "close method terminates ActorSystem" in {
+      val system = ActorSystem()
+      system.close()
+      system.whenTerminated.isCompleted should ===(true)
+    }
+
+    "Scala's Using automatically terminates ActorSystem" in {
+      var currentSystem: ActorSystem = null
+      Using(ActorSystem()) { system =>
+        currentSystem = system
+      }
+      currentSystem.whenTerminated.isCompleted should ===(true)
+    }
+
     "allow configuration of guardian supervisor strategy" in {
       implicit val system =
         ActorSystem(

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-tests/src/test/java/org/apache/pekko/actor/typed/ActorSystemTest.java

@@ -15,6 +15,7 @@
 
 import static java.util.concurrent.TimeUnit.SECONDS;
 import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
 
 import java.util.concurrent.CompletionStage;
 import org.apache.pekko.Done;
@@ -39,4 +40,15 @@ public void testGetWhenTerminatedWithoutTermination() {
         ActorSystem.create(Behaviors.empty(), "GetWhenTerminatedWithoutTermination");
     assertFalse(system.getWhenTerminated().toCompletableFuture().isDone());
   }
+
+  @Test
+  public void testTryWithResources() throws Exception {
+    ActorSystem<Void> system = null;
+    try (ActorSystem<Void> actorSystem =
+        ActorSystem.create(Behaviors.empty(), "TryWithResourcesSystem")) {
+      system = actorSystem;
+    }
+    final CompletionStage<Done> cs = system.getWhenTerminated();
+    assertTrue(cs.toCompletableFuture().isDone());
+  }
 }

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

@@ -18,6 +18,7 @@
 package org.apache.pekko.actor.typed
 
 import scala.annotation.nowarn
+import scala.util.Using
 
 import org.apache.pekko
 import pekko.actor.typed.scaladsl.Behaviors
@@ -45,5 +46,19 @@ class ActorSystemSpec extends PekkoSpec {
         system.terminate()
       }
     }
+
+    "close method terminates ActorSystem" in {
+      val system = ActorSystem(Behaviors.empty[String], "close-terminates-system")
+      system.close()
+      system.whenTerminated.isCompleted should ===(true)
+    }
+
+    "Scala's Using automatically terminates ActorSystem" in {
+      var currentSystem: ActorSystem[Nothing] = null
+      Using(ActorSystem(Behaviors.empty[String], "using-terminates-system")) { system =>
+        currentSystem = system
+      }
+      currentSystem.whenTerminated.isCompleted should ===(true)
+    }
   }
 }

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

@@ -0,0 +1,20 @@
+# 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[ReversedMissingMethodProblem]("org.apache.pekko.actor.typed.ActorSystem.close")
+ProblemFilters.exclude[InheritedNewAbstractMethodProblem]("org.apache.pekko.actor.typed.ActorSystem.close")

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,12 @@ 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.
+    # This timeout will also be used when ActorSystem's are automatically
+    # terminated by using Java's try-with-resources or Scala's
+    # scala.util.Using
+    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,14 @@ private[pekko] class ActorSystemImpl(
     whenTerminated
   }
 
+  override def close(): Unit = {
+    terminate()
+    val duration =
+      Duration(settings.config.getDuration("pekko.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)

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

@@ -16,8 +16,6 @@ package org.apache.pekko.actor
 import java.util.concurrent.TimeUnit
 
 import scala.annotation.tailrec
-import scala.concurrent.Await
-import scala.concurrent.duration._
 
 import BenchmarkActors._
 import org.openjdk.jmh.annotations._
@@ -78,10 +76,8 @@ class ForkJoinActorBenchmark {
   }
 
   @TearDown(Level.Trial)
-  def shutdown(): Unit = {
-    system.terminate()
-    Await.ready(system.whenTerminated, 15.seconds)
-  }
+  def shutdown(): Unit =
+    system.close()
 
   //  @Benchmark
   //  @OperationsPerInvocation(totalMessagesTwoActors)

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

@@ -15,7 +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._
@@ -40,10 +39,8 @@ class RouterPoolCreationBenchmark {
   var size = 0
 
   @TearDown(Level.Trial)
-  def shutdown(): Unit = {
-    system.terminate()
-    Await.ready(system.whenTerminated, 15.seconds)
-  }
+  def shutdown(): Unit =
+    system.close()
 
   @Benchmark
   @OutputTimeUnit(TimeUnit.MICROSECONDS)