feat: Add close method on ActorSystem (apache#2486)

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/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")