Add pseudo real time simulation environment

This commit adds a pseudo real time environment with the ability to switch between real time and virtual time. Furthermore, it adds a test that shows the general idea. When switching from virtual time to real time, the remaining time of following events is delayed. A factor can be used to scale real time execution times.

Author: abeham

src/SimSharp/Core/Environment.cs

@@ -8,6 +8,8 @@
 using System;
 using System.Collections.Generic;
 using System.IO;
+using System.Threading;
+using System.Threading.Tasks;
 
 namespace SimSharp {
   /// <summary>
@@ -177,7 +179,7 @@ public virtual object Run(DateTime until) {
       return Run(stopEvent);
     }
 
-    protected bool _stopRequested = false;
+    protected CancellationTokenSource _stop = null;
     /// <summary>
     /// Run until a certain event is processed.
     /// </summary>
@@ -192,7 +194,7 @@ public virtual object Run(DateTime until) {
     /// <param name="stopEvent">The event that stops the simulation.</param>
     /// <returns></returns>
     public virtual object Run(Event stopEvent = null) {
-      _stopRequested = false;
+      _stop = new CancellationTokenSource();
       if (stopEvent != null) {
         if (stopEvent.IsProcessed) {
           return stopEvent.Value;
@@ -201,21 +203,21 @@ public virtual object Run(Event stopEvent = null) {
       }
       OnRunStarted();
       try {
-        var stop = ScheduleQ.Count == 0 || _stopRequested;
+        var stop = ScheduleQ.Count == 0 || _stop.IsCancellationRequested;
         while (!stop) {
           Step();
           ProcessedEvents++;
-          stop = ScheduleQ.Count == 0 || _stopRequested;
+          stop = ScheduleQ.Count == 0 || _stop.IsCancellationRequested;
         }
       } catch (StopSimulationException e) { OnRunFinished(); return e.Value; }
       OnRunFinished();
       if (stopEvent == null) return null;
-      if (!_stopRequested && !stopEvent.IsTriggered) throw new InvalidOperationException("No scheduled events left but \"until\" event was not triggered.");
+      if (!_stop.IsCancellationRequested && !stopEvent.IsTriggered) throw new InvalidOperationException("No scheduled events left but \"until\" event was not triggered.");
       return stopEvent.Value;
     }
 
     public virtual void StopAsync() {
-      _stopRequested = true;
+      _stop?.Cancel();
     }
 
     public event EventHandler RunStarted;
@@ -786,7 +788,7 @@ public override void Schedule(TimeSpan delay, Event @event, int priority = 0) {
     /// <param name="stopEvent">The event that stops the simulation.</param>
     /// <returns></returns>
     public override object Run(Event stopEvent = null) {
-      _stopRequested = false;
+      _stop = new CancellationTokenSource();
       if (stopEvent != null) {
         if (stopEvent.IsProcessed) {
           return stopEvent.Value;
@@ -797,19 +799,19 @@ public override object Run(Event stopEvent = null) {
       try {
         var stop = false;
         lock (_locker) {
-          stop = ScheduleQ.Count == 0 || _stopRequested;
+          stop = ScheduleQ.Count == 0 || _stop.IsCancellationRequested;
         }
         while (!stop) {
           Step();
           ProcessedEvents++;
           lock (_locker) {
-            stop = ScheduleQ.Count == 0 || _stopRequested;
+            stop = ScheduleQ.Count == 0 || _stop.IsCancellationRequested;
           }
         }
       } catch (StopSimulationException e) { OnRunFinished(); return e.Value; }
       OnRunFinished();
       if (stopEvent == null) return null;
-      if (!_stopRequested && !stopEvent.IsTriggered) throw new InvalidOperationException("No scheduled events left but \"until\" event was not triggered.");
+      if (!_stop.IsCancellationRequested && !stopEvent.IsTriggered) throw new InvalidOperationException("No scheduled events left but \"until\" event was not triggered.");
       return stopEvent.Value;
     }
 
@@ -855,6 +857,72 @@ public override DateTime Peek() {
     }
   }
 
+  public class PseudoRealTimeSimulation : ThreadSafeSimulation {
+    private const double DefaultRealTimeFactor = 1.0;
+    private const double RealTimeThreshold = 1000.0;
+
+    public double RealTimeFactor { get; private set; } = DefaultRealTimeFactor;
+    public bool IsRunningInRealTime => RealTimeFactor < RealTimeThreshold;
+
+    public PseudoRealTimeSimulation() : this(new DateTime(1970, 1, 1)) { }
+    public PseudoRealTimeSimulation(TimeSpan? defaultStep) : this(new DateTime(1970, 1, 1), defaultStep) { }
+    public PseudoRealTimeSimulation(DateTime initialDateTime, TimeSpan? defaultStep = null) : this(new PcgRandom(), initialDateTime, defaultStep) { }
+    public PseudoRealTimeSimulation(int randomSeed, TimeSpan? defaultStep = null) : this(new DateTime(1970, 1, 1), randomSeed, defaultStep) { }
+    public PseudoRealTimeSimulation(DateTime initialDateTime, int randomSeed, TimeSpan? defaultStep = null) : this(new PcgRandom(randomSeed), initialDateTime, defaultStep) { }
+    public PseudoRealTimeSimulation(IRandom random, DateTime initialDateTime, TimeSpan? defaultStep = null) : base(random, initialDateTime, defaultStep) { }
+
+    public override void StopAsync() {
+      base.StopAsync();
+    }
+
+    public override void Step() {
+      lock (_locker) {
+        if (IsRunningInRealTime) {
+          var next = ScheduleQ.First.PrimaryPriority;
+          var delay = next - Now;
+          if (RealTimeFactor != 1.0) delay = TimeSpan.FromMilliseconds(delay.Milliseconds * 1.0 / RealTimeFactor);
+          if (delay > TimeSpan.Zero) Task.Delay(delay, _stop.Token).Wait();
+        }
+      }
+      base.Step();
+    }
+
+    /// <summary>
+    /// Switches the simulation to virtual time mode. In this mode, events
+    /// are processed without delay just like in a ThreadSafeSimulation.
+    /// </summary>
+    public virtual void SwitchToVirtualTime() {
+      lock (_locker) {
+        RealTimeFactor = RealTimeThreshold;
+      }
+    }
+
+    /// <summary>
+    /// Switches the simulation to real time mode. The real time factor of
+    /// this default mode is configurable.
+    /// </summary>
+    /// <remarks>
+    /// Per default, a <see cref="PseudoRealTimeSimulation"/> is executed
+    /// in real time with a simulation speed factor of 1.0.
+    /// 
+    /// With a factor of 1.0, a timeout of 5.0 seconds would delay the
+    /// simulation for 5.0 seconds. With a factor of 2.0, the same timeout
+    /// would delay the simulation for 2.5 seconds, whereas a factor of
+    /// 0.5 would delay the simulation for 10.0 seconds.
+    /// </remarks>
+    /// <param name="realTimeFactor">A factor greater than 0.0 used to scale real time events (higher value = faster execution).</param>
+    public virtual void SwitchToRealTime(double realTimeFactor = DefaultRealTimeFactor) {
+      lock (_locker) {
+        if (RealTimeFactor <= 0.0) throw new ArgumentException("The simulation speed scaling factor must not be negative.", nameof(realTimeFactor));
+        if (realTimeFactor >= RealTimeThreshold) {
+          SwitchToVirtualTime();
+        } else {
+          RealTimeFactor = realTimeFactor;
+        }
+      }
+    }
+  }
+
   /// <summary>
   /// Environments hold the event queues, schedule and process events.
   /// </summary>

src/Tests/EnvironmentTests.cs

@@ -8,6 +8,7 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using System.Threading.Tasks;
 using Xunit;
 
 namespace SimSharp.Tests {
@@ -164,5 +165,81 @@ public void EnvironmentBackwardsCompat() {
 0.65864875161591829, 0.46713487767696055, -0.37878389025311837};
       Assert.Equal(old, rndNumbers);
     }
+
+    [Fact]
+    public void PseudoRealTimeEnvTestStopTest() {
+      var then = DateTime.UtcNow;
+      var env = new PseudoRealTimeSimulation();
+      env.Run(TimeSpan.FromSeconds(1));
+      var now = DateTime.UtcNow;
+      Assert.True(now - then >= TimeSpan.FromSeconds(1));
+
+      var t = Task.Run(() => env.Run(TimeSpan.FromMinutes(1)));
+      Task.Delay(TimeSpan.FromMilliseconds(200)).Wait();
+      env.StopAsync();
+      Task.Delay(TimeSpan.FromMilliseconds(200)).Wait();
+      Assert.True(t.IsCompleted);
+    }
+
+    [Fact]
+    public void PseudoRealTimeEnvTest() {
+      var then = DateTime.UtcNow;
+      var delay = TimeSpan.FromSeconds(1);
+      var env = new PseudoRealTimeSimulation();
+      env.Process(RealTimeDelay(env, delay));
+      env.Run();
+      var now = DateTime.UtcNow;
+      Assert.True(now - then >= delay);
+    }
+
+    private IEnumerable<Event> RealTimeDelay(Simulation env, TimeSpan delay) {
+      yield return env.Timeout(delay);
+    }
+
+    [Fact]
+    public void MixedPseudoRealTimeEnvTest() {
+      var delay0 = TimeSpan.FromSeconds(8.0);
+      var delay1 = TimeSpan.FromSeconds(1.0);
+      var delay2 = TimeSpan.FromSeconds(5.0);
+      var env = new PseudoRealTimeSimulation();
+
+      // process 1
+      env.Process(MixedTestRealTimeDelay(env, delay0, delay1, delay2)); // should take at least 8 - 6 + 1 = 3 seconds in real time
+      // process 2
+      env.Process(MixedTestVirtualTimeDelay(env, delay0, delay1, delay2)); // should take 1 second in real and 5 seconds in virtual time
+
+      var then = DateTime.UtcNow;
+      env.Run();
+      var now = DateTime.UtcNow;
+      Assert.True(now - then >= delay0 - delay2); // delay2 is virtual
+    }
+
+    // yields events for process 1
+    private IEnumerable<Event> MixedTestRealTimeDelay(PseudoRealTimeSimulation env, TimeSpan delay0, TimeSpan delay1, TimeSpan delay2) {
+      Assert.True(env.Now == env.StartDate);
+      var then = DateTime.UtcNow;
+      yield return env.Timeout(delay0);
+      var now = DateTime.UtcNow;
+      Assert.True(env.Now == env.StartDate + delay0);
+      Assert.True(now - then >= delay0 - delay2); // delay2 is virtual
+    }
+
+    // yields events for process 2
+    private IEnumerable<Event> MixedTestVirtualTimeDelay(PseudoRealTimeSimulation env, TimeSpan delay0, TimeSpan delay1, TimeSpan delay2) {
+      Assert.True(env.Now == env.StartDate);
+      var then = DateTime.UtcNow;
+      yield return env.Timeout(delay1); // delays 1 second in real time
+      var now = DateTime.UtcNow;
+      Assert.True(env.Now == env.StartDate + delay1);
+      Assert.True(now - then >= delay1);
+
+      env.SwitchToVirtualTime();
+
+      yield return env.Timeout(delay2); // delays 5 seconds in virtual time
+      Assert.True(env.Now == env.StartDate + delay1 + delay2);
+
+      // switch back to real time happens at virtual time 00:00:06
+      env.SwitchToRealTime(); // real time timeout in process 1 should delay at least 8 - 6 + 1 = 3 seconds
+    }
   }
 }