Add shutdown reason to exit code propagation by Arkatufus · Pull Request #7680 · akkadotnet/akka.net

Arkatufus · 2025-06-06T19:31:23Z

Changes

Add exit code output to ActorSystem WhenTerminated property and .Terminate() method task.
If the CoordinatedShutdown stack was run, its reason will be propagated to the WhenTerminated task.
If "exit-clr" is set, the exit code will be passed to the Environment.Exit() call.
Exit codes conforms to the Linux exit code convention

See: https://manpages.ubuntu.com/manpages/lunar/man3/sysexits.h.3head.html
See: https://manpages.ubuntu.com/manpages/noble/man3/EXIT_SUCCESS.3const.html

Possible Exit Codes

Exit code	Description
0	`ActorSystem` shutdown cleanly due to `.Terminate()`, `.Abort()`, or normal cluster events
1	Unknown shutdown cause
3	[CLUSTER] `ActorSystem` terminated because it is downed
4	[CLUSTER] `ActorSystem` terminated because it failed to join the cluster

Arkatufus

self-review

src/core/Akka/Actor/CoordinatedShutdown.cs

Arkatufus · 2025-06-06T19:36:01Z

src/core/Akka/Actor/CoordinatedShutdown.cs

                            if (exitClr && !coord._runningClrHook)
                            {
-                                Environment.Exit(0);
+                                Environment.Exit(coord.ShutdownReason?.ExitCode ?? 0);


We propagate the exit code to the process exit code, if it is requested

Arkatufus · 2025-06-06T19:36:14Z

src/core/Akka/Actor/CoordinatedShutdown.cs

-                    else
-                    {
-                        return TaskEx.Completed;
+                        Environment.Exit(Get(system).ShutdownReason?.ExitCode ?? 0);


We propagate the exit code to the process exit code, if it is requested

Arkatufus · 2025-06-06T19:39:09Z

src/core/Akka/Actor/Internal/ActorSystemImpl.cs

+            _atomicRef = new AtomicReference<Task?>(new Task(() =>
+            {
+                // CoordinatedShutdown must be fetched in a lazy way because it might not be initialized yet.
+                var exitCode = CoordinatedShutdown.Get(system).ShutdownReason?.ExitCode ?? FinalExitCode;
+                _terminationPromise.TrySetResult(exitCode);
+            }));


TerminationCallbacks now uses a TaskCompletionSource for the final task. This is cleaner than relying on task continuation chain result.

Arkatufus · 2025-06-06T19:40:10Z

src/core/Akka/Actor/CoordinatedShutdown.cs

+                };
+            }
+
+            public abstract int ExitCode { get; }


Each Reason implementation will need to declare their exit codes.

Aaronontheweb

Feedback

src/core/Akka/Actor/CoordinatedShutdown.cs

Arkatufus · 2025-06-06T20:06:14Z

src/core/Akka/Actor/CoordinatedShutdown.cs

+        internal enum CommonExitCodes
+        {
+            Ok = 0,
+            UnknownReason = 1,
+            // Exit code 2 is reserved for Linux Bash for "Incorrect Usage"
+            ClusterDowned = 3,
+            ClusterJoinFailed = 4,
+            // Exit codes 64-78 is reserved by Linux sysexits.h
+            // Exit codes 126 and above is reserved by Linux shell
+        }


Updated error code list

That looks good to me

Arkatufus · 2025-06-06T20:06:50Z

src/core/Akka/Actor/CoordinatedShutdown.cs

+                ReasonMap = new Dictionary<int, string>
+                {
+                    [(int)CommonExitCodes.Ok] = "ActorSystem shutdown successfully",
+                    [(int)CommonExitCodes.UnknownReason] = "Unknown shutdown reason",
+                    [(int)CommonExitCodes.ClusterDowned] = "Cluster node downed",
+                    [(int)CommonExitCodes.ClusterJoinFailed] = "Cluster join unsuccessful",


Updated human readable code mapping

Aaronontheweb

LGTM, but why are the multi-node tests exiting in under 8 minutes? Did we introduce an error here that causes those not to run reliably? Or could that have happened as a result of earlier binary updates we made?

…minated`

Aaronontheweb

I think this needs to be redesigned in a fresh PR - concerns got mixed up here, namely trying to jam ActorSystem.Terminate() into the exit code infrastructure, and even after trying to clean that up the concerns are still really messy here.

IMHO - we should:

Just add an ExitCode property to the Reason type
Set the application's ExitCode to that value in the place where we do it currently.
Have this value default to 0 when unset, preserving current behavior.
Not touch the ActorSystem class at all.
I wouldn't even worry about writing tests for this - not really necessary or practical IMHO.

Aaronontheweb · 2025-06-10T14:22:46Z

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

        public abstract Akka.Actor.IScheduler Scheduler { get; }
        public abstract Akka.Serialization.Serialization Serialization { get; }
        public abstract Akka.Actor.Settings Settings { get; }
+        public abstract Akka.Actor.CoordinatedShutdown.Reason ShutdownReason { get; }


I don't believe we need this property here any longer, no?

Aaronontheweb · 2025-06-10T14:24:07Z

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

+        public async Task ActorSystem_shutdown_reason_must_be_Ok()
+        {
+            await Sys.Terminate();
+            Sys.ShutdownReason.ExitCode.Should().Be(0);


Yeah I think we want to keep the ActorSystem decoupled from this - totally a CoordinatedShutdown concern.

Aaronontheweb · 2025-06-10T14:53:32Z

src/core/Akka/Actor/CoordinatedShutdown.cs


            }
+
+            public static void RegisterReason(int code, string reason)


This should not be necessary - passing the reason into the CoordinatedShutdown.Run method should be sufficient.

Add shutdown reason to exit code propagation

d8d4187

Arkatufus commented Jun 6, 2025

View reviewed changes

Aaronontheweb added the akka-actor label Jun 6, 2025

Aaronontheweb requested changes Jun 6, 2025

View reviewed changes

src/core/Akka/Actor/CoordinatedShutdown.cs Show resolved Hide resolved

src/core/Akka/Actor/CoordinatedShutdown.cs Show resolved Hide resolved

Simplify code

c7b37bf

Arkatufus commented Jun 6, 2025

View reviewed changes

Aaronontheweb requested changes Jun 6, 2025

View reviewed changes

Arkatufus and others added 5 commits June 7, 2025 03:55

Revert signature change from .Terminate(), .Abort(), and `WhenTer…

36ff44e

…minated`

Revert public API changes

346addc

Update API Approval list

848f156

Merge branch 'dev' into akkadotnet#7517-Add-shutdown-exit-code

ce2057c

Merge branch 'dev' into akkadotnet#7517-Add-shutdown-exit-code

8a1ac5e

Aaronontheweb requested changes Jun 10, 2025

View reviewed changes

Arkatufus mentioned this pull request Jun 10, 2025

Propagate CoordinatedShutdown reason to application exit code #7684

Merged

Aaronontheweb closed this Jun 10, 2025

Arkatufus deleted the #7517-Add-shutdown-exit-code branch June 20, 2025 14:12

Conversation

Arkatufus commented Jun 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Possible Exit Codes

Uh oh!

Arkatufus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Aaronontheweb left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Aaronontheweb left a comment

Choose a reason for hiding this comment

Uh oh!

Aaronontheweb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Arkatufus commented Jun 6, 2025 •

edited

Loading

Aaronontheweb left a comment •

edited

Loading