add WatchAysnc methods for monitoring actor lifecycles outside of A…

…kka.NET (#6102)

* prototyping `WatchAysnc` methods

* cleaned up `GracefulStop` and `PromiseActorRef` internals

* implemented `WatchAsync`

src/core/Akka.API.Tests/verify/CoreAPISpec.ApproveCore.Core.verified.txt

@@ -1882,6 +1882,10 @@ namespace Akka.Actor
         public Akka.Actor.IStash Stash { get; set; }
     }
     public delegate void UntypedReceive(object message);
+    public class static WatchAsyncSupport
+    {
+        public static System.Threading.Tasks.Task<bool> WatchAsync(this Akka.Actor.IActorRef target, System.Threading.CancellationToken token = null) { }
+    }
     public class static WrappedMessage
     {
         public static object Unwrap(object message) { }

src/core/Akka.API.Tests/verify/CoreAPISpec.ApproveCore.DotNet.verified.txt

@@ -1884,6 +1884,10 @@ namespace Akka.Actor
         public Akka.Actor.IStash Stash { get; set; }
     }
     public delegate void UntypedReceive(object message);
+    public class static WatchAsyncSupport
+    {
+        public static System.Threading.Tasks.Task<bool> WatchAsync(this Akka.Actor.IActorRef target, System.Threading.CancellationToken token = null) { }
+    }
     public class static WrappedMessage
     {
         public static object Unwrap(object message) { }

src/core/Akka.API.Tests/verify/CoreAPISpec.ApproveCore.Net.verified.txt

@@ -1882,6 +1882,10 @@ namespace Akka.Actor
         public Akka.Actor.IStash Stash { get; set; }
     }
     public delegate void UntypedReceive(object message);
+    public class static WatchAsyncSupport
+    {
+        public static System.Threading.Tasks.Task<bool> WatchAsync(this Akka.Actor.IActorRef target, System.Threading.CancellationToken token = null) { }
+    }
     public class static WrappedMessage
     {
         public static object Unwrap(object message) { }

src/core/Akka.Tests/Actor/GracefulStopSpecs.cs

@@ -51,7 +51,7 @@ public async Task GracefulStopShouldReturnTrueForAlreadyDeadActor()
 
         private class CustomShutdown{}
 
-        [Fact(DisplayName = "GracefulStop should return false if shutdown goes overtime", Skip = "GracefulStop currently throws a TaskCancellationException, which seems wrong")]
+        [Fact(DisplayName = "GracefulStop should return false if shutdown goes overtime")]
         public async Task GracefulStopShouldThrowIfShutdownGoesOvertime()
         {
             // arrange

src/core/Akka.Tests/Actor/WatchAsyncSpecs.cs

@@ -0,0 +1,71 @@
+//-----------------------------------------------------------------------
+// <copyright file="WatchAsyncSpecs.cs" company="Akka.NET Project">
+//     Copyright (C) 2009-2023 Lightbend Inc. <http://www.lightbend.com>
+//     Copyright (C) 2013-2023 .NET Foundation <https://github.com/akkadotnet/akka.net>
+// </copyright>
+//-----------------------------------------------------------------------
+
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using Akka.Actor;
+using Akka.TestKit;
+using Akka.TestKit.TestActors;
+using FluentAssertions;
+using Xunit;
+
+namespace Akka.Tests.Actor
+{
+    public class WatchAsyncSpecs : AkkaSpec
+    {
+        [Fact(DisplayName = "WatchAsync should return true when actor is terminated")]
+        public async Task WatchAsync_should_return_true_when_actor_is_terminated()
+        {
+            // arrange
+            var actor = Sys.ActorOf(BlackHoleActor.Props);
+            using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(3));
+            var terminatedTask = actor.WatchAsync(cts.Token);
+
+            // act
+            Sys.Stop(actor);
+            var terminated = await terminatedTask;
+
+            // assert
+            terminated.Should().BeTrue();
+        }
+
+        [Fact(DisplayName = "WatchAsync should return true when called on actor that is already terminated")]
+        public async Task WatchAsync_should_return_true_when_actor_is_already_terminated()
+        {
+            // arrange
+            var actor = Sys.ActorOf(BlackHoleActor.Props);
+            Watch(actor);
+            Sys.Stop(actor);
+            await ExpectTerminatedAsync(actor);
+
+            // act
+
+            using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(3));
+            var terminated = await actor.WatchAsync(cts.Token);
+
+            // assert
+            terminated.Should().BeTrue();
+        }
+
+        [Fact(DisplayName = "WatchAsync should return false when cancellation token is cancelled")]
+        public async Task WatchAsync_should_return_true_when_cancelled()
+        {
+            // arrange
+            var actor = Sys.ActorOf(BlackHoleActor.Props);
+            using var cts = new CancellationTokenSource();
+            var terminatedTask = actor.WatchAsync(cts.Token);
+
+            // act
+            cts.Cancel();
+            var terminated = await terminatedTask;
+
+            // assert
+            terminated.Should().BeFalse();
+        }
+    }
+}