Package com.amalgamasimulation.engine

Class Engine

java.lang.Object
com.amalgamasimulation.engine.Engine
All Implemented Interfaces:
Timeable
public class Engine extends Object implements Timeable
Class representing the simulation engine. The engine allows its users to schedule events and execute them at some specified time scale. The engine can be reused to start the simulation over again. The engine is designed to run in concurrence with visualization: visualization actions are executed in between simulation events and do not interfere with them.

The engine can be run both synchronously and asynchronously. Synchronous execution can be used for running models fast in background without visualization. Asynchronous execution is typically used for running models with visualization.

Author:
Andrey Malykhanov

  • Constructor Summary

    Constructors
    Constructor
    Description
    Engine()
    Creates a new instance of the simulation engine

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addStateChangedHandler(Runnable handler)
    Adds the specified handler of this engine state change event.
    LocalDateTime
    beginDate()
    Returns the begin date, i.e.
    boolean
    catchExceptions()
    Returns the value of exceptions catching flag.
    LocalDateTime
    date()
    Returns the current simulation date.
    int
    eventsCount()
    Returns the number of events that are scheduled but not yet executed
    Event
    execute(int sequence, Runnable runnable)
    If this engine is running, executes the action at current simulation time with the specified sequence.
    Event
    execute(Runnable runnable)
    If this engine is running, executes the action at current simulation time with maximum priority.
    long
    executedEventsCount()
    Returns the number of events completely executed by the engine since its creation or last reset
    boolean
    fastMode()
    Checks whether fast mode flag is set
    List<Event>
    getEvents()
    Returns the unmodifiable list of events that are scheduled but not yet executed
    double
    getEventsExecutionTimeFraction()
    Returns the ratio of events execution time and total run time, i.e.
    List<Exception>
    getExceptions()
    Returns the unmodifiable list of exceptions thrown in events action code during simulation run.
    double
    getTotalEventsExecutionTimeMillis()
    Returns the total duration of execution of all simulation events since last engine start, in milliseconds
    double
    getTotalRunTimeMillis()
    Returns the total duration of run since last engine start, in milliseconds.
    boolean
    isRunning()
    Checks whether this engine is currently running
    boolean
    isRunningFast()
    Checks if this engine is running in fast mode.
    void
    reset()
    Resets the simulation engine, sets its time to zero.
    void
    run()
    Starts or resumes running the engine asynchronously and returns immediately.
    void
    run(boolean blockUntilStopped)
    Starts or resumes running the engine either synchronously or asynchronously, depending on the value of the argument.
    Event
    scheduleAbsolute(double absoluteTime, int sequence, Runnable runnable)
    Schedules an event for execution at the specified absolute time with the specified priority
    Event
    scheduleAbsolute(double absoluteTime, Runnable runnable)
    Schedules an event for execution at the specified absolute time with the priority equal to 0
    Event
    scheduleRelative(double timeout, int sequence, Runnable runnable)
    Schedules an event for execution in the specified timeout from the current simulation time with the specified priority.
    Event
    scheduleRelative(double timeout, Runnable runnable)
    Schedules an event for execution in the specified timeout from the current simulation time with the priority equal to 0.
    Event
    scheduleStop(double absoluteTime, int sequence, String description)
    Schedules a stoppage of this engine at the specified absolute time with the specified priority
    Event
    scheduleStop(double absoluteTime, String description)
    Schedules a stoppage of this engine at the specified absolute time with the priority equal to 0
    void
    setCatchExceptions(boolean catchExceptions)
    Sets the value of exceptions catching flag.
    void
    setFastMode(boolean fastMode)
    Switches between the fast and normal modes of events execution.
    void
    setTemporal(LocalDateTime beginDate, ChronoUnit timeUnit)
    Sets the temporal parameters of the engine.
    void
    setTimeScale(double timeScale)
    Sets the new simulation time scale.
    void
    setTraceEvents(boolean traceEvents)
    Sets the value of event tracing flag.
    void
    stop()
    Stops running this engine.
    double
    time()
    Returns the current simulation time
    double
    timeScale()
    Returns current simulation time scale, i.e.
    ChronoUnit
    timeUnit()
    Returns the simulation time unit, i.e.
    boolean
    traceEvents()
    Returns the value of event tracing flag.
    void
    visualize(Object target, Runnable procedure)
    Enqueues the request for a visualization procedure.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface com.amalgamasimulation.utils.time.Timeable

    dateToTime, dateToTime, day, duration, hour, minute, second, timeToDate, week, wholeDays, wholeDays, wholeHours, wholeHours, wholeUnits

  • Constructor Details

    • Engine

      public Engine()
      Creates a new instance of the simulation engine

  • Method Details

    • reset

      public void reset()
      Resets the simulation engine, sets its time to zero. If this engine is running, stops the engine before resetting.

    • setTemporal

      public void setTemporal(LocalDateTime beginDate, ChronoUnit timeUnit)
      Sets the temporal parameters of the engine. The temporal parameters are used to map model time to model date and backwards. Such conversion is made by Timeable.dateToTime(LocalDateTime) and Timeable.timeToDate(double) methods.

      Conceptually, simulation calendar date is calculated with the following formula: 

       date() == beginDate() + time() * timeUnit()

      It is impossible to set the temporal parameters if the engine is running or is in the middle of simulation run, i.e. when time() > 0. In these cases, a IllegalStateException will be thrown
      Parameters:
      beginDate - date that corresponds to zero simulation time
      timeUnit - time unit that corresponds to 1 simulation time unit
      See Also:

    • run

      public void run()
      Starts or resumes running the engine asynchronously and returns immediately. Does nothing if this engine is already running

    • run

      public void run(boolean blockUntilStopped)
      Starts or resumes running the engine either synchronously or asynchronously, depending on the value of the argument.

      If blockUntilStopped = false, the behavior of the method is the same as run(), i.e. it starts running the engine asynchronously and returns immediately

      If blockUntilStopped = true, starts running the model synchronously and returns after this engine is stopped first time e.g. by calling stop() method from inside some simulation event.

      Parameters:
      blockUntilStopped - whether or not to block until the simulation is stopped

    • addStateChangedHandler

      public void addStateChangedHandler(Runnable handler)
      Adds the specified handler of this engine state change event. Such events include:
    • stopping this engine if it was running,
    • starting this engine if it was stopped,
    • changing the time scale of this engine,
    • switching between fast and normal modes.
      • Parameters:
      handler - action to be executed in the case of engine state change

    • setFastMode

      public void setFastMode(boolean fastMode)
      Switches between the fast and normal modes of events execution. In fast mode, the events are executed one after another without any real time scale. If this engine is running, the change applies immediately. Otherwise, the change applies only after engine starts running
      Parameters:
      fastMode - whether to switch on or off the fast mode

    • isRunningFast

      public boolean isRunningFast()
      Checks if this engine is running in fast mode. If this engine is not running, returns false
      Returns:
      true if this engine is running in fast mode, false otherwise

    • isRunning

      public boolean isRunning()
      Checks whether this engine is currently running
      Returns:
      true if this engine is running, false otherwise

    • stop

      public void stop()
      Stops running this engine. Does nothing if this engine is currently not running

    • visualize

      public void visualize(Object target, Runnable procedure)
      Enqueues the request for a visualization procedure. The actual time of performing this visualization procedure is determined by this engine internally.
      Parameters:
      target - some object which the visualization procedure is associated with. Must be specified to prevent calling several visualization procedures for the same target unnecessarily
      procedure - visualization procedure to be executed

    • fastMode

      public boolean fastMode()
      Checks whether fast mode flag is set
      Returns:
      true if fast mode flag is set, false otherwise

    • setTimeScale

      public void setTimeScale(double timeScale)
      Sets the new simulation time scale.

      If this engine is running in normal (not fast) mode, the time scale change takes effect immediately. If this engine is running in fast mode, there is no immediate effect of this call, but the change may be applied after fast mode is switched off.

      If this engine is not running, the change will take effect after the engine starts running in normal mode.

      If zero or negative time scale is passed, throws a RuntimeException

      Parameters:
      timeScale - new time scale

    • scheduleStop

      public Event scheduleStop(double absoluteTime, int sequence, String description)
      Schedules a stoppage of this engine at the specified absolute time with the specified priority
      Parameters:
      absoluteTime - absolute time, i.e. simulation time passed since start of this engine
      sequence - priority among other events scheduled for the same time. The less this number, the more the priority of execution. Integer.MIN_VALUE corresponds to maximum priority
      description - description of the stop event
      Returns:
      event that was created to execute the engine stoppage

    • scheduleStop

      public Event scheduleStop(double absoluteTime, String description)
      Schedules a stoppage of this engine at the specified absolute time with the priority equal to 0
      Parameters:
      absoluteTime - absolute time, i.e. simulation time passed since start of this engine
      description - description of the stop event
      Returns:
      event that was created to execute the engine stoppage

    • scheduleAbsolute

      public Event scheduleAbsolute(double absoluteTime, int sequence, Runnable runnable)
      Schedules an event for execution at the specified absolute time with the specified priority
      Parameters:
      absoluteTime - absolute time, i.e. simulation time passed since start of this engine
      sequence - priority among other events scheduled for the same time. The less this number, the more the priority of execution. Integer.MIN_VALUE corresponds to maximum priority
      runnable - action to be executed
      Returns:
      event that was created to execute the specified action

    • scheduleAbsolute

      public Event scheduleAbsolute(double absoluteTime, Runnable runnable)
      Schedules an event for execution at the specified absolute time with the priority equal to 0
      Parameters:
      absoluteTime - absolute time, i.e. simulation time passed since start of this engine
      runnable - action to be executed
      Returns:
      event that was created to execute the specified action

    • scheduleRelative

      public Event scheduleRelative(double timeout, int sequence, Runnable runnable)
      Schedules an event for execution in the specified timeout from the current simulation time with the specified priority.

      Zero timeout is allowed, negative timeouts are not allowed and will result in throwing a RuntimeException

      Parameters:
      timeout - timeout from the current simulation time in which the specified action will be executed
      sequence - priority among other events scheduled for the same time. The less this number, the more the priority of execution. Integer.MIN_VALUE corresponds to maximum priority
      runnable - action to be executed
      Returns:
      that was created to execute the specified action

    • scheduleRelative

      public Event scheduleRelative(double timeout, Runnable runnable)
      Schedules an event for execution in the specified timeout from the current simulation time with the priority equal to 0.

      Zero timeout is allowed, negative timeouts are not allowed and will result in throwing a RuntimeException

      Parameters:
      timeout - timeout from the current simulation time in which the specified action will be executed
      runnable - action to be executed
      Returns:
      that was created to execute the specified action

    • execute

      public Event execute(int sequence, Runnable runnable)
      If this engine is running, executes the action at current simulation time with the specified sequence. If the engine is not running, schedules execution of action at current time. The less the sequence number, the more priority of action's execution will be
      Parameters:
      sequence - sequence number. Integer.MIN_VALUE corresponds to maximum execution priority among all events and actions scheduled at current simulation time
      runnable - action to be executed
      Returns:
      event that was created to execute the specified action

    • execute

      public Event execute(Runnable runnable)
      If this engine is running, executes the action at current simulation time with maximum priority. If the engine is not running, schedules execution of action at current time
      Parameters:
      runnable - action to be executed
      Returns:
      event that was created to execute the specified action

    • timeScale

      public double timeScale()
      Returns current simulation time scale, i.e. number of simulation time units that engine attempts to simulate in 1 second of real time
      Returns:
      current simulation time scale
      See Also:

    • eventsCount

      public int eventsCount()
      Returns the number of events that are scheduled but not yet executed
      Returns:
      number of events and actions that are scheduled but not yet executed

    • executedEventsCount

      public long executedEventsCount()
      Returns the number of events completely executed by the engine since its creation or last reset
      Returns:
      number of executed events

    • getEvents

      public List<Event> getEvents()
      Returns the unmodifiable list of events that are scheduled but not yet executed
      Returns:
      unmodifiable list of events that are scheduled but not yet executed

    • time

      public double time()
      Returns the current simulation time
      Returns:
      current simulation time

    • getTotalRunTimeMillis

      public double getTotalRunTimeMillis()
      Returns the total duration of run since last engine start, in milliseconds. The duration excludes the time the execution was stopped
      Returns:
      total duration of run since last engine start, in milliseconds

    • getTotalEventsExecutionTimeMillis

      public double getTotalEventsExecutionTimeMillis()
      Returns the total duration of execution of all simulation events since last engine start, in milliseconds
      Returns:
      total duration of execution of all simulation events since last engine start, in milliseconds

    • getEventsExecutionTimeFraction

      public double getEventsExecutionTimeFraction()
      Returns the ratio of events execution time and total run time, i.e. getTotalEventsExecutionTimeMillis()/getTotalRunTimeMillis(). The result is calculated since last engine start
      Returns:
      ratio of events execution time and total run time

    • getExceptions

      public List<Exception> getExceptions()
      Returns the unmodifiable list of exceptions thrown in events action code during simulation run. The exceptions are being caught and collected inside this engine if exceptions catching flag is set to true using setCatchExceptions(boolean) method.
      Returns:
      unmodifiable list of exceptions

    • date

      public LocalDateTime date()
      Returns the current simulation date. The date is calculated using current simulation time and temporal parameters, i.e. begin date and time unit.
      Returns:
      current simulation date
      See Also:

    • setTraceEvents

      public void setTraceEvents(boolean traceEvents)
      Sets the value of event tracing flag. If event tracing flag is set to true, the engine creates all events as traceable events. Traceable events remember stack trace of the point in code from where it was scheduled

      Tracing events can be useful for debugging because it is sometimes useful to understand where a problematic event was scheduled from. It is not recommended to use event tracing in productive models because calculating and storing stack trace of each event requires significant computational resources

      Parameters:
      traceEvents - value of event tracing flag
      See Also:

    • traceEvents

      public boolean traceEvents()
      Returns the value of event tracing flag. If event tracing flag is set to true, the engine creates all events as traceable events. Traceable events remember stack trace of the point in code from where it was scheduled

      Tracing events can be useful for debugging because it is sometimes useful to understand where a problematic event was scheduled from. It is not recommended to use event tracing in productive models because calculating and storing stack trace of each event requires significant computational resources

      Returns:
      value of event tracing flag
      See Also:

    • catchExceptions

      public boolean catchExceptions()
      Returns the value of exceptions catching flag. If the flag is set to true, all exceptions thrown inside event actions will be caught and collected inside this engine. They can be retrieved using getExceptions() method
      Returns:
      value of exceptions catching flag

    • setCatchExceptions

      public void setCatchExceptions(boolean catchExceptions)
      Sets the value of exceptions catching flag. If the flag is set to true, all exceptions thrown inside event actions will be caught and collected inside this engine. They can be retrieved using getExceptions() method

    • beginDate

      public LocalDateTime beginDate()
      Description copied from interface: Timeable
      Returns the begin date, i.e. the simulation date that corresponds to zero simulation time
      Specified by:
      beginDate in interface Timeable
      Returns:
      simulation date that corresponding to zero simulation time

    • timeUnit

      public ChronoUnit timeUnit()
      Description copied from interface: Timeable
      Returns the simulation time unit, i.e. period unit that corresponds to one unit of simulation time
      Specified by:
      timeUnit in interface Timeable
      Returns:
      period unit that corresponds to one unit of simulation time