Finish implementation of pseudo realtime simulation and increase target

to .NET Core 2.1

 * Fix interrupting the realtime delay
 * Add unit tests
 * Introduce a PseudoRealtimeProcess that will always reset the
 environment to realtime

Author: abeham

src/Benchmark/Benchmark.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>netcoreapp2.0</TargetFramework>
+    <TargetFramework>netcoreapp2.1</TargetFramework>
     <Authors>Andreas Beham</Authors>
     <Version>3.2</Version>
     <Company>HEAL, FH Upper Austria</Company>

src/Samples/Samples.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>netcoreapp2.0</TargetFramework>
+    <TargetFramework>netcoreapp2.1</TargetFramework>
     <Version>3.2</Version>
     <Authors>Andreas Beham</Authors>
     <Company>HEAL, FH Upper Austria</Company>

src/SimSharp/Core/Environment.cs

@@ -7,6 +7,7 @@
 
 using System;
 using System.Collections.Generic;
+using System.Diagnostics;
 using System.IO;
 using System.Threading;
 using System.Threading.Tasks;
@@ -17,7 +18,7 @@ namespace SimSharp {
   /// </summary>
   /// <remarks>
   /// This class is not thread-safe against manipulation of the event queue. If you supply a termination
-  /// event that is set outside the simulation, please use the <see cref="ThreadSafeSimulation"/> environment.
+  /// event that is set outside the simulation thread, please use the <see cref="ThreadSafeSimulation"/> environment.
   /// 
   /// For most purposes <see cref="Simulation"/> is however the better and faster choice.
   /// </remarks>
@@ -37,10 +38,11 @@ public double NowD {
       get { return (Now - StartDate).TotalSeconds / DefaultTimeStepSeconds; }
     }
 
+    private DateTime now;
     /// <summary>
     /// The current simulation time as a calendar date.
     /// </summary>
-    public DateTime Now { get; protected set; }
+    public virtual DateTime Now { get => now; protected set => now = value; }
 
     /// <summary>
     /// The calendar date when the simulation started. This defaults to 1970-1-1 if
@@ -206,7 +208,6 @@ public virtual object Run(Event stopEvent = null) {
         var stop = ScheduleQ.Count == 0 || _stop.IsCancellationRequested;
         while (!stop) {
           Step();
-          ProcessedEvents++;
           stop = ScheduleQ.Count == 0 || _stop.IsCancellationRequested;
         }
       } catch (StopSimulationException e) { OnRunFinished(); return e.Value; }
@@ -242,6 +243,7 @@ public virtual void Step() {
       Now = next.PrimaryPriority;
       evt = next.Event;
       evt.Process();
+      ProcessedEvents++;
     }
 
     /// <summary>
@@ -373,6 +375,7 @@ public TimeSpan RandExponential(TimeSpan mean) {
 
     private bool useSpareNormal = false;
     private double spareNormal = double.NaN;
+
     /// <summary>
     /// Uses the Marsaglia polar method to generate a random variable
     /// from two uniform random distributed values.
@@ -803,7 +806,6 @@ public override object Run(Event stopEvent = null) {
         }
         while (!stop) {
           Step();
-          ProcessedEvents++;
           lock (_locker) {
             stop = ScheduleQ.Count == 0 || _stop.IsCancellationRequested;
           }
@@ -815,6 +817,23 @@ public override object Run(Event stopEvent = null) {
       return stopEvent.Value;
     }
 
+    public Task<object> RunAsync(TimeSpan duration) {
+      return Task.Run(() => Run(duration));
+    }
+
+    public Task<object> RunAsync(DateTime until) {
+      return Task.Run(() => Run(until));
+    }
+
+    /// <summary>
+    /// Run until a certain event is processed, but does not block.
+    /// </summary>
+    /// <param name="stopEvent">The event that stops the simulation.</param>
+    /// <returns></returns>
+    public Task<object> RunAsync(Event stopEvent = null) {
+      return Task.Run(() => Run(stopEvent));
+    }
+
     /// <summary>
     /// Performs a single step of the simulation, i.e. process a single event
     /// </summary>
@@ -829,6 +848,7 @@ public override void Step() {
         evt = next.Event;
       }
       evt.Process();
+      ProcessedEvents++;
     }
 
     /// <summary>
@@ -857,60 +877,115 @@ public override DateTime Peek() {
     }
   }
 
-  public class PseudoRealTimeSimulation : ThreadSafeSimulation {
-    private const double DefaultRealTimeFactor = 1.0;
-
-    public double? RealTimeFactor { get; protected set; } = DefaultRealTimeFactor;
-    public bool IsRunningInRealTime => RealTimeFactor.HasValue;
+  /// <summary>
+  /// Provides a simulation environment where delays in simulation time may result in a similar
+  /// delay in wall-clock time. The environment is not an actual realtime simulation environment
+  /// in that there is no guarantee that 3 seconds in model time are also exactly 3 seconds in
+  /// observed wall-clock time. This simulation environment is a bit slower, as the overhead of
+  /// the simulation kernel (event creation, queuing, processing, etc.) is not accounted for.
+  /// 
+  /// However, it features a switch between virtual and realtime, thus allowing it to be used
+  /// in contexts where realtime is only necessary sometimes (e.g. during interaction with
+  /// long-running co-processes). Such use cases may arise in simulation control problems.
+  /// </summary>
+  public class PseudoRealtimeSimulation : ThreadSafeSimulation {
+    public const double DefaultRealtimeScale = 1;
 
-    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) { }
+    /// <summary>
+    /// The scale at which the simulation runs in comparison to realtime. A value smaller
+    /// than 1 results in longer-than-realtime delays, while a value larger than 1 results
+    /// in shorter-than-realtime delays. A value of exactly 1 is realtime.
+    /// </summary>
+    public double? RealtimeScale { get; protected set; } = DefaultRealtimeScale;
+    /// <summary>
+    /// Whether a non-null <see cref="RealtimeScale"/> has been set.
+    /// </summary>
+    public bool IsRunningInRealtime => RealtimeScale.HasValue;
 
-    public override void StopAsync() {
-      base.StopAsync();
+    private object _timeLocker = new object();
+    /// <summary>
+    /// The current model time. Note that, while in realtime, this may continuously change.
+    /// </summary>
+    public override DateTime Now {
+      get { lock (_timeLocker) { return base.Now + _rtDelayTime.Elapsed; } }
+      protected set => base.Now = value;
     }
 
-    protected CancellationTokenSource _delay = null;
+    protected CancellationTokenSource _rtDelayCtrl = null;
+    protected Stopwatch _rtDelayTime = new Stopwatch();
+
+
+    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) { }
+    
+    protected override EventQueueNode DoSchedule(DateTime date, Event @event, int priority = 0) {
+      if (ScheduleQ.Count > 0 && date < ScheduleQ.First.PrimaryPriority) _rtDelayCtrl?.Cancel();
+      return base.DoSchedule(date, @event, priority);
+    }
 
     public override void Step() {
-      if (IsRunningInRealTime) {
+      var delay = TimeSpan.Zero;
+      double? rtScale = null;
+      lock (_locker) {
+        if (IsRunningInRealtime) {
+          rtScale = RealtimeScale;
+          var next = ScheduleQ.First.PrimaryPriority;
+          delay = next - base.Now;
+          if (rtScale.Value != 1.0) delay = TimeSpan.FromMilliseconds(delay.TotalMilliseconds / rtScale.Value);
+          _rtDelayCtrl = CancellationTokenSource.CreateLinkedTokenSource(_stop.Token);
+        }
+      }
+
+      if (delay > TimeSpan.Zero) {
+        _rtDelayTime.Start();
+        Task.Delay(delay, _rtDelayCtrl.Token).ContinueWith(_ => { }).Wait();
+        _rtDelayTime.Stop();
+        var observed = _rtDelayTime.Elapsed;
+
         lock (_locker) {
-          if (IsRunningInRealTime) {
-            var next = ScheduleQ.First.PrimaryPriority;
-            var delay = next - Now;
-            if (RealTimeFactor.Value != 1.0) delay = TimeSpan.FromMilliseconds(delay.Milliseconds / RealTimeFactor.Value);
-            if (delay > TimeSpan.Zero) {
-              _delay = CancellationTokenSource.CreateLinkedTokenSource(_stop.Token);
-              var then = DateTime.UtcNow;
-              Task.Delay(delay, _delay.Token).Wait();
-              if (_delay.IsCancellationRequested) {
-                var now = DateTime.UtcNow;
-                var observedDelay = now - then;
-                if (observedDelay < delay) {
-                  Now += observedDelay;
-                  return; // next event is not processed
-                }
-              }
+          if (rtScale.Value != 1.0) observed = TimeSpan.FromMilliseconds(observed.TotalMilliseconds / rtScale.Value);
+          if (_rtDelayCtrl.IsCancellationRequested && observed < delay) {
+            lock (_timeLocker) {
+              Now = base.Now + observed;
+              _rtDelayTime.Reset();
             }
+            return; // next event is not processed, step is not actually completed
           }
         }
       }
-      base.Step();
+
+      Event evt;
+      lock (_locker) {
+        var next = ScheduleQ.Dequeue();
+        lock (_timeLocker) {
+          _rtDelayTime.Reset();
+          Now = next.PrimaryPriority;
+        }
+        evt = next.Event;
+      }
+      evt.Process();
+      ProcessedEvents++;
     }
 
     /// <summary>
-    /// Switches the simulation to virtual time mode. In this mode, events
-    /// are processed without delay just like in a <see cref="ThreadSafeSimulation"/>.
+    /// Switches the simulation to virtual time mode, i.e., running as fast as possible.
+    /// In this mode, events are processed without delay just like in a <see cref="ThreadSafeSimulation"/>.
     /// </summary>
-    public virtual void SwitchToVirtualTime() {
-      if (!IsRunningInRealTime) return;
+    /// <remarks>
+    /// An ongoing real-time delay is being canceled when this method is called. Usually, this
+    /// is only the case when this method is called from a thread other than the main simulation thread.
+    /// 
+    /// If the simulation is already in virtual time mode, this method has no effect.
+    /// </remarks>
+    public virtual void SetVirtualtime() {
       lock (_locker) {
-        RealTimeFactor = null;
-        _delay?.Cancel(); // TODO: Same lock region
+        if (!IsRunningInRealtime) return;
+        RealtimeScale = null;
+        _rtDelayCtrl?.Cancel();
       }
     }
 
@@ -919,21 +994,37 @@ public virtual void SwitchToVirtualTime() {
     /// 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.
+    /// If this method is called while running in real-time mode, but given a different
+    /// <paramref name="realtimeScale"/>, the current delay is canceled and the remaining
+    /// time is delayed using the new time factor.
     /// 
-    /// 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.
+    /// The default factor is 1, i.e., real time - a timeout of 5 seconds would cause
+    /// a wall-clock delay of 5 seconds. With a factor of 2, the delay as measured by
+    /// a wall clock would be 2.5 seconds, whereas a factor of 0.5, a wall-clock delay of
+    /// 10 seconds would be observed.
     /// </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) {
+    /// <param name="realtimeScale">A value strictly greater than 0 used to scale real time events.</param>
+    public virtual void SetRealtime(double realtimeScale = DefaultRealtimeScale) {
       lock (_locker) {
-        if (realTimeFactor <= 0.0) throw new ArgumentException("The simulation speed scaling factor must be strictly positive.", nameof(realTimeFactor));
-        RealTimeFactor = realTimeFactor;
+        if (realtimeScale <= 0.0) throw new ArgumentException("The simulation speed scaling factor must be strictly positive.", nameof(realtimeScale));
+        if (IsRunningInRealtime && realtimeScale != RealtimeScale) _rtDelayCtrl?.Cancel();
+        RealtimeScale = realtimeScale;
       }
     }
+
+    /// <summary>
+    /// This is only a convenience for mixed real- and virtual time simulations.
+    /// It creates a new pseudo realtime process which will set the simulation
+    /// to realtime every time it continues (e.g., if it has been set to virtual time).
+    /// The process is automatically scheduled to be started at the current simulation time.
+    /// </summary>
+    /// <param name="generator">The generator function that represents the process.</param>
+    /// <param name="priority">The priority to rank events at the same time (smaller value = higher priority).</param>
+    /// <param name="realtimeScale">A value strictly greater than 0 used to scale real time events (1 = realtime).</param>
+    /// <returns>The scheduled process that was created.</returns>
+    public Process PseudoRealtimeProcess(IEnumerable<Event> generator, int priority = 0, double realtimeScale = DefaultRealtimeScale) {
+      return new PseudoRealtimeProcess(this, generator, priority, realtimeScale);
+    }
   }
 
   /// <summary>

src/SimSharp/Core/Events/Process.cs

@@ -153,4 +153,31 @@ public Initialize(Simulation environment, Process process, int priority)
       }
     }
   }
+
+  public class PseudoRealtimeProcess : Process {
+    public double RealtimeScale { get; set; }
+
+    public new PseudoRealtimeSimulation Environment {
+      get { return (PseudoRealtimeSimulation)base.Environment; }
+    }
+
+    /// <summary>
+    /// Sets up a new process.
+    /// The process places an initialize event into the event queue which starts
+    /// the process by retrieving events from the generator.
+    /// </summary>
+    /// <param name="environment">The environment in which the process lives.</param>
+    /// <param name="generator">The generator function of the process.</param>
+    /// <param name="priority">The priority if multiple processes are started at the same time.</param>
+    /// <param name="realtimeScale">A value strictly greater than 0 used to scale real time events (1 = realtime).</param>
+    public PseudoRealtimeProcess(PseudoRealtimeSimulation environment, IEnumerable<Event> generator, int priority = 0, double realtimeScale = PseudoRealtimeSimulation.DefaultRealtimeScale)
+      : base(environment, generator, priority) {
+      RealtimeScale = realtimeScale;
+    }
+
+    protected override void Resume(Event @event) {
+      Environment.SetRealtime(RealtimeScale);
+      base.Resume(@event);
+    }
+  }
 }