Akka.Actor: Added built-in IntentionalRestart message to test actor restart behaviors (#7493)

Aaronontheweb · web-flow · commit 1f5688d146f4 · 2025-02-04T05:24:44.000+07:00
* Added `Restart` message to trigger intentional restarts close #7492 * renamed to `IntentionalRestart` * added API approvals
diff --git a/src/core/Akka.API.Tests/verify/CoreAPISpec.ApproveCore.DotNet.verified.txt b/src/core/Akka.API.Tests/verify/CoreAPISpec.ApproveCore.DotNet.verified.txt
@@ -1264,6 +1264,15 @@ namespace Akka.Actor
         public Akka.Actor.IActorRef Watch(Akka.Actor.IActorRef subject) { }
         public Akka.Actor.IActorRef WatchWith(Akka.Actor.IActorRef subject, object message) { }
     }
+    public sealed class IntentionalActorRestartException : Akka.Actor.AkkaException
+    {
+        public IntentionalActorRestartException() { }
+    }
+    public sealed class IntentionalRestart : Akka.Actor.IAutoReceivedMessage
+    {
+        public static Akka.Actor.IntentionalRestart Instance { get; }
+        public override string ToString() { }
+    }
     [Akka.Annotations.InternalApiAttribute()]
     public abstract class InternalActorRefBase : Akka.Actor.ActorRefBase, Akka.Actor.IActorRef, Akka.Actor.IActorRefScope, Akka.Actor.ICanTell, Akka.Actor.IInternalActorRef, Akka.Util.ISurrogated, System.IComparable, System.IComparable<Akka.Actor.IActorRef>, System.IEquatable<Akka.Actor.IActorRef>
     {
diff --git a/src/core/Akka.API.Tests/verify/CoreAPISpec.ApproveCore.Net.verified.txt b/src/core/Akka.API.Tests/verify/CoreAPISpec.ApproveCore.Net.verified.txt
@@ -1262,6 +1262,15 @@ namespace Akka.Actor
         public Akka.Actor.IActorRef Watch(Akka.Actor.IActorRef subject) { }
         public Akka.Actor.IActorRef WatchWith(Akka.Actor.IActorRef subject, object message) { }
     }
+    public sealed class IntentionalActorRestartException : Akka.Actor.AkkaException
+    {
+        public IntentionalActorRestartException() { }
+    }
+    public sealed class IntentionalRestart : Akka.Actor.IAutoReceivedMessage
+    {
+        public static Akka.Actor.IntentionalRestart Instance { get; }
+        public override string ToString() { }
+    }
     [Akka.Annotations.InternalApiAttribute()]
     public abstract class InternalActorRefBase : Akka.Actor.ActorRefBase, Akka.Actor.IActorRef, Akka.Actor.IActorRefScope, Akka.Actor.ICanTell, Akka.Actor.IInternalActorRef, Akka.Util.ISurrogated, System.IComparable, System.IComparable<Akka.Actor.IActorRef>, System.IEquatable<Akka.Actor.IActorRef>
     {
diff --git a/src/core/Akka.Remote.Tests/Serialization/MiscMessageSerializerSpec.cs b/src/core/Akka.Remote.Tests/Serialization/MiscMessageSerializerSpec.cs
@@ -159,6 +159,13 @@ public void Can_serialize_Kill()
             AssertEqual(kill);
         }
 
+        [Fact]
+        public void Can_serialize_IntentionalRestart()
+        {
+            var restart = IntentionalRestart.Instance;
+            AssertEqual(restart);
+        }
+
         [Fact]
         public void Can_serialize_PoisonPill()
         {
diff --git a/src/core/Akka.Remote/Configuration/Remote.conf b/src/core/Akka.Remote/Configuration/Remote.conf
@@ -37,6 +37,7 @@ akka {
       "Akka.Actor.ActorIdentity, Akka" = akka-misc
       "Akka.Actor.IActorRef, Akka" = akka-misc
       "Akka.Actor.PoisonPill, Akka" = akka-misc
+      "Akka.Actor.IntentionalRestart, Akka" = akka-misc
       "Akka.Actor.Kill, Akka" = akka-misc
       "Akka.Actor.PoisonPill, Akka" = akka-misc
       "Akka.Actor.Status+Failure, Akka" = akka-misc
diff --git a/src/core/Akka.Remote/Serialization/MiscMessageSerializer.cs b/src/core/Akka.Remote/Serialization/MiscMessageSerializer.cs
@@ -28,6 +28,7 @@ public sealed class MiscMessageSerializer : SerializerWithStringManifest
         private const string ActorRefManifest = "AR";
         private const string PoisonPillManifest = "PP";
         private const string KillManifest = "K";
+        private const string IntentionalRestartManifest = "IR";
         private const string RemoteWatcherHearthbeatManifest = "RWHB";
         private const string RemoteWatcherHearthbeatRspManifest = "RWHR";
         private const string LocalScopeManifest = "LS";
@@ -74,6 +75,7 @@ public override byte[] ToBinary(object obj)
                 case PoisonPill _:
                 case Kill _:
                 case RemoteWatcher.Heartbeat _:
+                case IntentionalRestart _:
                     return EmptyBytes;
                 case RemoteWatcher.HeartbeatRsp heartbeatRsp:
                     return HeartbeatRspToProto(heartbeatRsp);
@@ -125,6 +127,8 @@ public override string Manifest(object obj)
                     return PoisonPillManifest;
                 case Kill _:
                     return KillManifest;
+                case IntentionalRestart _:
+                    return IntentionalRestartManifest;
                 case RemoteWatcher.Heartbeat _:
                     return RemoteWatcherHearthbeatManifest;
                 case RemoteWatcher.HeartbeatRsp _:
@@ -177,6 +181,8 @@ public override object FromBinary(byte[] bytes, string manifest)
                     return PoisonPill.Instance;
                 case KillManifest:
                     return Kill.Instance;
+                case IntentionalRestartManifest:
+                    return IntentionalRestart.Instance;
                 case RemoteWatcherHearthbeatManifest:
                     return RemoteWatcher.Heartbeat.Instance;
                 case RemoteWatcherHearthbeatRspManifest:
diff --git a/src/core/Akka.Tests/Actor/ActorLifeCycleSpec.cs b/src/core/Akka.Tests/Actor/ActorLifeCycleSpec.cs
@@ -22,28 +22,28 @@ public class ActorLifeCycleSpec : AkkaSpec
     {
         public class LifeCycleTestActor : UntypedActor
         {
-            private AtomicCounter generationProvider;
-            private string id;
-            private IActorRef testActor;
-            private int CurrentGeneration;
+            private AtomicCounter _generationProvider;
+            private readonly string _id;
+            private readonly IActorRef _testActor;
+            private readonly int _currentGeneration;
             public LifeCycleTestActor(IActorRef testActor,string id,AtomicCounter generationProvider)
             {
-                this.testActor = testActor;
-                this.id = id;
-                this.generationProvider = generationProvider;
-                this.CurrentGeneration = generationProvider.Next();
+                _testActor = testActor;
+                _id = id;
+                _generationProvider = generationProvider;
+                _currentGeneration = generationProvider.Next();
             }
 
             private void Report(object message)
             {
-                testActor.Tell(((string)message,id,CurrentGeneration));
+                _testActor.Tell(((string)message,_id,_currentGeneration));
             }
 
             protected override void OnReceive(object message)
             {
                 if (message is string s && s == "status")
                 {
-                    testActor.Tell(("OK",id,CurrentGeneration));
+                    _testActor.Tell(("OK",_id,_currentGeneration));
                 }
             }
 
@@ -323,16 +323,16 @@ public class Count { }
 
         public class KillableActor : UntypedActor
         {
-            private IActorRef testActor;
+            private readonly IActorRef _testActor;
             public KillableActor(IActorRef testActor)
             {
-                this.testActor = testActor;
+                _testActor = testActor;
             }
 
             protected override void PostStop()
             {
                 Debug.WriteLine("inside poststop");
-                testActor.Tell(("Terminated", Self.Path.Name));
+                _testActor.Tell(("Terminated", Self.Path.Name));
             }
 
             protected override void OnReceive(object message)
@@ -378,7 +378,7 @@ public async Task Clear_child_upon_terminated()
         }
 
 
-        class MyCustomException : Exception {}
+        private class MyCustomException : Exception {}
 
         [Fact(DisplayName="PreRestart should receive correct cause, message and sender")]
         public async Task Call_PreStart_with_correct_message_and_sender()
@@ -393,7 +393,12 @@ public async Task Call_PreStart_with_correct_message_and_sender()
                 c.OnPreRestart = (ex, mess, context) =>
                 {
                     TestActor.Tell(ex);
-                    TestActor.Tell(mess);
+                    
+                    // can't relay the Restart back because that will blow up the TestActor
+                    if (mess is not IntentionalRestart)
+                    {
+                        TestActor.Tell(mess);
+                    }
                     TestActor.Tell(context.Sender);
                 };
             });
@@ -405,6 +410,11 @@ public async Task Call_PreStart_with_correct_message_and_sender()
             await ExpectMsgAsync<MyCustomException>();
             await ExpectMsgAsync(message);
             await ExpectMsgAsync(TestActor);
+            
+            // test the `Restart` built-in message
+            broken.Tell(IntentionalRestart.Instance);
+            await ExpectMsgAsync<IntentionalActorRestartException>();
+            await ExpectMsgAsync(TestActor);
         }
     }
 }
diff --git a/src/core/Akka/Actor/ActorCell.DefaultMessages.cs b/src/core/Akka/Actor/ActorCell.DefaultMessages.cs
@@ -132,27 +132,38 @@ protected internal virtual void AutoReceiveMessage(Envelope envelope)
 
             switch (message)
             {
+                case ActorSelectionMessage selectionMessage:
+                    ReceiveSelection(selectionMessage);
+                    break;
+                case Identify identify:
+                    HandleIdentity(identify);
+                    break;
                 case Terminated terminated:
                     ReceivedTerminated(terminated);
                     break;
+                case PoisonPill _:
+                    HandlePoisonPill();
+                    break;
                 case AddressTerminated terminated:
                     AddressTerminated(terminated.Address);
                     break;
                 case Kill _:
                     Kill();
                     break;
-                case PoisonPill _:
-                    HandlePoisonPill();
-                    break;
-                case ActorSelectionMessage selectionMessage:
-                    ReceiveSelection(selectionMessage);
-                    break;
-                case Identify identify:
-                    HandleIdentity(identify);
+                case Akka.Actor.IntentionalRestart:
+                    TriggerIntentionalRestart();
                     break;
             }
         }
 
+        /// <summary>
+        /// Done in response to receiving a <see cref="IntentionalRestart"/> message.
+        /// </summary>
+        private static void TriggerIntentionalRestart()
+        {
+            throw new IntentionalActorRestartException();
+        }
+
         /// <summary>
         /// This is only intended to be called from TestKit's TestActorRef
         /// </summary>
diff --git a/src/core/Akka/Actor/Exceptions.cs b/src/core/Akka/Actor/Exceptions.cs
@@ -256,6 +256,17 @@ protected LoggerInitializationException(SerializationInfo info, StreamingContext
         }
     }
 
+    /// <summary>
+    /// Thrown when an actor is sent a <see cref="IntentionalRestart"/> message.
+    /// </summary>
+    /// <remarks>
+    /// Meant to be used primarily for testing purposes.
+    /// </remarks>
+    public sealed class IntentionalActorRestartException : AkkaException
+    {
+        public IntentionalActorRestartException() : base("Intentional actor restart") { }
+    }
+
     /// <summary>
     /// This exception is thrown when a <see cref="Kill"/> message has been sent to an Actor.
     /// <see cref="SupervisorStrategy.DefaultDecider"/> will by default stop the actor.
diff --git a/src/core/Akka/Actor/IAutoReceivedMessage.cs b/src/core/Akka/Actor/IAutoReceivedMessage.cs
@@ -213,6 +213,21 @@ public override string ToString()
         }
     }
 
+    /// <summary>
+    /// Sending a <see cref="IntentionalRestart"/> message will force it to throw a <see cref="IntentionalActorRestartException"/>
+    /// when it processes the message.
+    /// </summary>
+    public sealed class IntentionalRestart : IAutoReceivedMessage
+    {
+        private IntentionalRestart() { }
+        public static IntentionalRestart Instance { get; } = new();
+        
+        public override string ToString()
+        {
+            return "<Restart>";
+        }
+    }
+
     /// <summary>
     /// Sending an <see cref="Kill"/> message to an actor causes the actor to throw an 
     /// <see cref="ActorKilledException"/> when it processes the message, which gets handled using the normal supervisor mechanism.

Original file line number	Diff line number	Diff line change
`@@ -159,6 +159,13 @@ public void Can_serialize_Kill()`
`159`	`159`	`AssertEqual(kill);`
`160`	`160`	`}`
`161`	`161`
	`162`	`+ [Fact]`
	`163`	`+ public void Can_serialize_IntentionalRestart()`
	`164`	`+ {`
	`165`	`+ var restart = IntentionalRestart.Instance;`
	`166`	`+ AssertEqual(restart);`
	`167`	`+ }`
	`168`	`+`
`162`	`169`	`[Fact]`
`163`	`170`	`public void Can_serialize_PoisonPill()`
`164`	`171`	`{`
Original file line number	Diff line number	Diff line change
`@@ -22,28 +22,28 @@ public class ActorLifeCycleSpec : AkkaSpec`
`22`	`22`	`{`
`23`	`23`	`public class LifeCycleTestActor : UntypedActor`
`24`	`24`	`{`
`25`		`- private AtomicCounter generationProvider;`
`26`		`- private string id;`
`27`		`- private IActorRef testActor;`
`28`		`- private int CurrentGeneration;`
	`25`	`+ private AtomicCounter _generationProvider;`
	`26`	`+ private readonly string _id;`
	`27`	`+ private readonly IActorRef _testActor;`
	`28`	`+ private readonly int _currentGeneration;`
`29`	`29`	`public LifeCycleTestActor(IActorRef testActor,string id,AtomicCounter generationProvider)`
`30`	`30`	`{`
`31`		`- this.testActor = testActor;`
`32`		`- this.id = id;`
`33`		`- this.generationProvider = generationProvider;`
`34`		`- this.CurrentGeneration = generationProvider.Next();`
	`31`	`+ _testActor = testActor;`
	`32`	`+ _id = id;`
	`33`	`+ _generationProvider = generationProvider;`
	`34`	`+ _currentGeneration = generationProvider.Next();`
`35`	`35`	`}`
`36`	`36`
`37`	`37`	`private void Report(object message)`
`38`	`38`	`{`
`39`		`- testActor.Tell(((string)message,id,CurrentGeneration));`
	`39`	`+ _testActor.Tell(((string)message,_id,_currentGeneration));`
`40`	`40`	`}`
`41`	`41`
`42`	`42`	`protected override void OnReceive(object message)`
`43`	`43`	`{`
`44`	`44`	`if (message is string s && s == "status")`
`45`	`45`	`{`
`46`		`- testActor.Tell(("OK",id,CurrentGeneration));`
	`46`	`+ _testActor.Tell(("OK",_id,_currentGeneration));`
`47`	`47`	`}`
`48`	`48`	`}`
`49`	`49`
`@@ -323,16 +323,16 @@ public class Count { }`
`323`	`323`
`324`	`324`	`public class KillableActor : UntypedActor`
`325`	`325`	`{`
`326`		`- private IActorRef testActor;`
	`326`	`+ private readonly IActorRef _testActor;`
`327`	`327`	`public KillableActor(IActorRef testActor)`
`328`	`328`	`{`
`329`		`- this.testActor = testActor;`
	`329`	`+ _testActor = testActor;`
`330`	`330`	`}`
`331`	`331`
`332`	`332`	`protected override void PostStop()`
`333`	`333`	`{`
`334`	`334`	`Debug.WriteLine("inside poststop");`
`335`		`- testActor.Tell(("Terminated", Self.Path.Name));`
	`335`	`+ _testActor.Tell(("Terminated", Self.Path.Name));`
`336`	`336`	`}`
`337`	`337`
`338`	`338`	`protected override void OnReceive(object message)`
`@@ -378,7 +378,7 @@ public async Task Clear_child_upon_terminated()`
`378`	`378`	`}`
`379`	`379`
`380`	`380`
`381`		`- class MyCustomException : Exception {}`
	`381`	`+ private class MyCustomException : Exception {}`
`382`	`382`
`383`	`383`	`[Fact(DisplayName="PreRestart should receive correct cause, message and sender")]`
`384`	`384`	`public async Task Call_PreStart_with_correct_message_and_sender()`
`@@ -393,7 +393,12 @@ public async Task Call_PreStart_with_correct_message_and_sender()`
`393`	`393`	`c.OnPreRestart = (ex, mess, context) =>`
`394`	`394`	`{`
`395`	`395`	`TestActor.Tell(ex);`
`396`		`- TestActor.Tell(mess);`
	`396`	`+`
	`397`	`+ // can't relay the Restart back because that will blow up the TestActor`
	`398`	`+ if (mess is not IntentionalRestart)`
	`399`	`+ {`
	`400`	`+ TestActor.Tell(mess);`
	`401`	`+ }`
`397`	`402`	`TestActor.Tell(context.Sender);`
`398`	`403`	`};`
`399`	`404`	`});`
`@@ -405,6 +410,11 @@ public async Task Call_PreStart_with_correct_message_and_sender()`
`405`	`410`	`await ExpectMsgAsync<MyCustomException>();`
`406`	`411`	`await ExpectMsgAsync(message);`
`407`	`412`	`await ExpectMsgAsync(TestActor);`
	`413`	`+`
	`414`	+ // test the `Restart` built-in message
	`415`	`+ broken.Tell(IntentionalRestart.Instance);`
	`416`	`+ await ExpectMsgAsync<IntentionalActorRestartException>();`
	`417`	`+ await ExpectMsgAsync(TestActor);`
`408`	`418`	`}`
`409`	`419`	`}`
`410`	`420`	`}`