#lang scribble/doc
@(require scribble/manual
          scribblings/icons
          (for-label scheme/base
                     plot/plot
                     "../simulation-with-graphics.ss"))

@title[#:tag "control-basic"]{Simulation Control (Basic)}

@local-table-of-contents[]

The PLT Scheme Simulation Collection provides functionality for basic simulation control.  Basic simulation control includes the simulation main loop for controlling the execution of event and processes, scheduling event and processes, and simulating the passing of time (i.e. waiting and working).

@section{Scheduling Events and Processes}

One of the main characteristics of discete simulation models is the ability to schedule procedureal simulation elements (e.g., events and processes) to occur at specified (sumulated) times.  Typically, an event list is maintained that contains entries for each of the schedule events.

In the simulation collection, each simulation environment has three such lists: the now event list, the future event list, and the continuous event list.  The now event list contains entries for elements that are to be executed before the simulation clock is advanced, i.e. now.  The future event list contains entries for elements that are to be executed in the (simulated) future, i.e. after the simulation clock advances.  The continuous event list is used for continuous simulation models and is described in Chapter 11 Continuous Simulation Models.

@defform*[#:id schedule #:literals (now at in when)
               ((schedule now (function . arguments)
                          #:priority (priority 100))
                (schedule (at time) (function . arguments)
                          #:priority (priority 100))
                (schedule (in duration) (function . arguments)
                          #:priority (priority 100))
                (schedule (when event) (function . arguments)
                          #:priority (priority 100))
                (schedule time (function . arguments)
                          #:priority (priority 100)))]{
@schemeblock[
function  : procedure?
arguments : (listof any/c)
time      : (>=/c 0.0)
duration  : (>=/c 0.0)
event     : event?
priority  : real?]
                                                      
Schedules events or processes for execution, optionally with a specified @scheme[priority].  If @scheme[function] is the name of a process, then a process instance is created and scheduled for execution with the specified @scheme[arguments].  Otherwise, @scheme[function] must evaluate to a procedural object and the function is scheduled for execution with the specified @scheme[arguments].

The timing of the event or process execution is specified using one of the following forms:

@itemize{
  @item{@scheme[now]---The event or process is scheduled to be executed now, i.e before the simulation clock is advanced.  That is, it is added to the now event list.}
  @item{@scheme[(at time)]---The event or process is scheduled at the specified @scheme[time].  An error is signaled if @scheme[time] is in the (simulated) past.  That is, @scheme[time] must be greater than or equal to @scheme[(current-simulation-time)].}
  @item{@scheme[(in duration)]---The event or process is scheduled to be executed after the specified @scheme[duration] has elapsed.  This is equivalent to @scheme[(at (+ duration (current-simulation-time)))].  An error is signaled if @scheme[duration] is negative.}
  @item{@scheme[(when event)]---The event or process is scheduled to be executed at the same time as (i.e. when) the specified @scheme[event] is executed.  This is called a @deftech{linked event}.}
  @item{@scheme[time]---This is equivalent to @scheme[(at time)].}
  }

Note that there is a subtle difference between @scheme[now] and @scheme[(in 0.0)] (or, equivalently, @scheme[(at (current-simulation-time))].  The @scheme[now] specification will add the event or process to the now event list while the @scheme[(in 0.0)] specification will add the event to the future event list.  In the simulation collection, advancing the simulation clock---even to the same time---allows simulation monitors to run and some other internal bookkeeping to occur.  The simulation clock never advances between now events; while it will always advance between future events, even if they are scheduled to occur at the same (simulated) time.  In essence, now event represent events that are causally linked to the current time; while future events schedules at the same time basically represent coindicidental timings.}

@section{Controlling the Simulation Main Loop}

The @deftech{simulation main loop} implements the simulation control strategy by executing events and processes and maintaining the simulation clock.

The following pseudo code shows the processing for the simulation main loop, including continuous simulation models.

@verbatim{
simulation main loop:
  save the exit continuation
  loop:
    save the next continuation
    if the now event list is not empty
      execute the next now (discrete) event
      else if the future event list is not empty
        if the continuous event list is not empty
          execute the continuous events until
                the time of the next future event
          ;; this may terminate early and reenter
          ;; the loop via the next continuation
          ;; (e.g. if a continuous process's exit
          ;; condition is met)
        else
          execute the next future (discrete) event
    else
      if the continuous event list is not empty
        execute the contnuous events forever
        ;; this may terminate early and reenter
        ;; the loop via the next continuation
        ;; otherwise, the loop would never end
      else
        exit
  end loop
end simulation main loop}

@defproc[(start-simulation) any]{
Begins execution of the simulation main loop in the current simulation environment.  It saves the @scheme[loop-next] and @scheme[loop-exit] continuations in the current simulation environment and then executes events and processes from the event list(s) until either there are no more to be executed or the simulation main loop is explicitly exited.}

@defproc[(stop-simulation) any]{
Terminates execution of the simulation main loop running in the current simulation environment.  It calls @scheme[(current-simulation-loop-exit)]}
           
A convenient usage of @scheme[stop-simulation] is to schedule its execution at a point in time the execution is to run until.  For example:

@schemeblock[
(schedule (at 1000.0) (stop-simulation))
]

will cause the simulation to end at (simulated) time 1000.0.

@section{Simulating Waiting and Working}

@defproc*[(((wait/work (delay (>=/c 0.0))) any)
           ((wait (delay (>=/c 0.0))) any)
           ((work (delay (>=/c 0.0))) any))]{
Simulates the passage of (simulated) time.  The event or process calling one of these function will wait for the specified @scheme[delay].  Note that @scheme[wait] and @scheme[work] are aliases for the @scheme[wait/work] function.}