title: Shutting down Orleans

This document explains how to gracefully shutdown an Orleans silo before application exit, first as a Console app, and then as a Docker container app.

Graceful shutdown - Console app

The following code shows how to gracefully shutdown an Orleans silo console app in response to the user pressing Ctrl+C, which generates the Console.CancelkeyPress event.

Normally when that event handler returns, the application will exit immediately, causing a catastrophic Orleans silo crash and loss of in-memory state. But in the sample code below, we set a.Cancel = true; to prevent the application closing before the Orleans silo has completed its graceful shutdown.

  1. using Microsoft.Extensions.Logging;
  2. using Orleans.Configuration;
  3. using Orleans.Hosting;
  4. using System;
  5. using System.Net;
  6. using System.Threading;
  7. using System.Threading.Tasks;
  9. namespace MySiloHost {
  11.     class Program {
  13.         static readonly ManualResetEvent _siloStopped = new ManualResetEvent(false);
  15.         static ISiloHost silo;
  16.         static bool siloStopping = false;
  17.         static readonly object syncLock = new object();
  19.         static void Main(string[] args) {
  21.             SetupApplicationShutdown();
  23.             silo = CreateSilo();
  24.             silo.StartAsync().Wait();
  26.             /// Wait for the silo to completely shutdown before exiting. 
  27.             _siloStopped.WaitOne();
  28.         }
  30.         static void SetupApplicationShutdown() {
  31.             /// Capture the user pressing Ctrl+C
  32.             Console.CancelKeyPress += (s, a) => {
  33.                 /// Prevent the application from crashing ungracefully.
  34.                 a.Cancel = true;
  35.                 /// Don't allow the following code to repeat if the user presses Ctrl+C repeatedly.
  36.                 lock (syncLock) {
  37.                     if (!siloStopping) {
  38.                         siloStopping = true;
  39.                         Task.Run(StopSilo).Ignore();
  40.                     }
  41.                 }
  42.                 /// Event handler execution exits immediately, leaving the silo shutdown running on a background thread,
  43.                 /// but the app doesn't crash because a.Cancel has been set = true
  44.             };
  45.         }
  47.         static ISiloHost CreateSilo() {
  48.             return new SiloHostBuilder()
  49.                 .Configure(options => options.ClusterId = "MyTestCluster")
  50.                 .UseDevelopmentClustering(options => options.PrimarySiloEndpoint = new IPEndPoint(IPAddress.Loopback, 11111))
  51.                 .ConfigureLogging(b => b.SetMinimumLevel(LogLevel.Debug).AddConsole())
  52.                 .Build();
  53.         }
  55.         static async Task StopSilo() {
  56.             await silo.StopAsync();
  57.             _siloStopped.Set();
  58.         }
  59.     }
  60. }

Of course, there are many other ways of achieving the same goal. Below is shown a way, popular online, and misleading, that DOES NOT work properly. It does not work because it sets up a race condition between two methods trying to exit first: the Console.CancelKeyPress event handler method, and the static void Main(string[] args) method. When the event handler method finishes first, which happens at least half the time, the application will hang instead of exiting smoothly.

  1. class Program {
  3.     static readonly ManualResetEvent _siloStopped = new ManualResetEvent(false);
  5.     static ISiloHost silo;
  6.     static bool siloStopping = false;
  7.     static readonly object syncLock = new object();
  9.     static void Main(string[] args) {
  11.         Console.CancelKeyPress += (s, a) => {
  12.             Task.Run(StopSilo);
  13.             /// Wait for the silo to completely shutdown before exiting. 
  14.             _siloStopped.WaitOne();
  15.             /// Now race to finish ... who will finish first?
  16.             /// If I finish first, the application will hang! :(
  17.         };
  19.         silo = CreateSilo();
  20.         silo.StartAsync().Wait();
  22.         /// Wait for the silo to completely shutdown before exiting. 
  23.         _siloStopped.WaitOne();
  24.         /// Now race to finish ... who will finish first?
  25.     }
  27.     static async Task StopSilo() {
  28.         await silo.StopAsync();
  29.         _siloStopped.Set();
  30.     }
  31. }

Graceful shutdown - Docker app

To be completed.