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

(cherry picked from commit d5ee8a6)

Author: mdedetrich

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

@@ -109,6 +109,10 @@ import pekko.util.FutureConverters._
   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

@@ -13,6 +13,8 @@
 
 package org.apache.pekko.actor;
 
+import static org.junit.Assert.assertTrue;
+
 import org.apache.pekko.testkit.PekkoJUnitActorSystemResource;
 import org.junit.Before;
 import org.junit.Rule;
@@ -48,4 +50,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-2.13+/org/apache/pekko/actor/ActorSystemScala213PlusSpec.scala

@@ -0,0 +1,38 @@
+/*
+ * 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.
+ */
+
+package org.apache.pekko.actor
+
+import scala.util.Using
+
+import org.scalatestplus.scalacheck.ScalaCheckPropertyChecks
+
+import org.apache.pekko.testkit.{ ImplicitSender, PekkoSpec }
+
+class ActorSystemScala213PlusSpec extends PekkoSpec(ActorSystemSpec.config) with ImplicitSender
+    with ScalaCheckPropertyChecks {
+  "A Scala 2.13+ ActorSystem" must {
+    "Scala's Using automatically terminates ActorSystem" in {
+      var currentSystem: ActorSystem = null
+      Using(ActorSystem()) { system =>
+        currentSystem = system
+      }
+      currentSystem.whenTerminated.isCompleted should ===(true)
+    }
+  }
+
+}

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

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

@@ -13,6 +13,8 @@
 
 package org.apache.pekko.actor.typed;
 
+import static org.junit.Assert.assertTrue;
+
 import org.apache.pekko.Done;
 import org.apache.pekko.actor.typed.javadsl.Behaviors;
 import org.junit.Test;
@@ -40,4 +42,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

@@ -17,6 +17,8 @@
 
 package org.apache.pekko.actor.typed
 
+import scala.util.Using
+
 import com.typesafe.config.ConfigFactory
 import org.apache.pekko
 import pekko.actor.typed.scaladsl.Behaviors
@@ -44,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 }
 
@@ -40,7 +40,7 @@ import pekko.util.Helpers.{ ConfigOps, Requiring }
  * 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] =>
 
   /**
@@ -145,6 +145,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 pekko.util.FutureConverters._
   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(