Events

In a simulation model, an event represents an action that will take place in the (simulated) future.

In the PLT Scheme Simulation Collection, an event represents the (simulated) future application of a procedural object to a list of arguments.

5.1  The event Structure

event

Structure:
event

Contract:

(struct event
        ((time (<=/c 0.0))
         (priority real?)
         (process (union/c process? #f))
         (function (union/c procedure? #f))
         (arguments list?)
         (event-list (union/c event-list? #f))
         (linked-event-list (union/c event-list? #f))))

This structure defines an event. Note that since the function field can contain any procedural object, including continuations, any event can call the wait/work function. This is a slight extension to the definition of event given above in that an event may represent a sequence of actions.

time - The (simulated) time the event is to occur.
priority - The priority of the event. Priorities are real numbers with higher numbers representing higher priority.
process - The process owning the event or #f.
function - The procedural object containing the code that represents the event or #f.
arguments - A list of the arguments for the function.
event-list - The event-list in which the event is currently stored or #f. This is used to unschedule an event from whatever event list it might be in.
linked-event-list - An event list storing linked events or #f. This is used to implement linked events (i.e. those scheduled using the (when event) clause.

make-event

Function:
(make-event time priority process function arguments)

Contract:

(-> real?
    real?
    (union/c process? #f)
    (union/c procedure? #f)
    (union/c list? #f))

The function returns a newly created event with the corresponding fields set to the values of time, priority, process, function, and arguments. The event-list and linked-event-list fields are initialized to #f.

Note that the make-event is not typically used in user code, instead the schedule macro is used to create and schedule an event.

5.2  Event Lists

An event list stores a list of events. Events are stored in order of their time values.

event-list

Structure:
event-list

Contract:

(struct event-list
        ((events list?)))

This structure defines an event list. The current implementation just encapsulates a list that stores the events.

events - A list of the events on the event list.

make-event-list

Function:
(make-event-list)

Contract:

(-> event-list?)

This function returns a new event list that is empty.

event-list-empty?

Function:
(event-list-empty? event-list)

Contract:

(-> event-list? boolean?)

This function returns true, #t, if the event-list is empty, and false, #f otherwise.

event-list-add"!

Function:
(event-list-add! event-list event)

Contract:

(-> event-list? event? any)

This function adds an event to an event list. Currently, the event list is ordered by time and priority.

event-list-remove!

Function:
(event-list-remove! event-list event)

Contract:

(-> event-list? event? any)

This function removes an event to an event list. No error is signaled if the specified event is not on the event-list.

event-list-pop!

Function:
(event-list-pop! event-list)

Contract:

(-> event-list? event?)

This function removes the first event from the event list and returns it.

5.3  Example - Functions as Events

This example is a simulation model of a simple system. Customer arrivals are exponentially distributed with an interrival time of 4.0 minutes. The time a customer remains in the system is uniformally distributed between 2.0 and 10.0 minutes. The output is a simple trace of customer arrivals and departures.

The PLT Scheme Science Collection provides the random distribution functions.

; Example 0 - Functions as Events

(require (planet "simulation.ss"
                 ("williams" "simulation.plt")))
(require (planet "random-distributions.ss"
                 ("williams" "science.plt")))

(define (generator n)
  (do ((i 0 (+ i 1)))
      ((= i n) (void))
    (wait (random-exponential 4.0))
    (schedule now (customer i))))

(define (customer i)
  (printf "~a: customer ~a enters~n"
         (current-simulation-time) i)
  (work (random-flat 2.0 10.0))
  (printf "~a: customer ~a leaves~n"
         (current-simulation-time) i))

(define (run-simulation n)
  (with-new-simulation-environment
   (schedule (at 0.0) (generator n))
   (start-simulation)))

The simulation model is executed by calling (run-simulation n), where n is the number of customer to simulate through the system. For example, (run-simulation 10) produces the following output:

>(run-simulation 10)
0.6153910608822503: customer 0 enters
5.599485116393393: customer 1 enters
6.411843645405005: customer 2 enters
8.48917994426752: customer 0 leaves
10.275428842274628: customer 1 leaves
14.749397986170655: customer 2 leaves
23.525886616767437: customer 3 enters
27.18604340910279: customer 3 leaves
32.1644631797164: customer 4 enters
33.14558760001698: customer 5 enters
39.67682614849173: customer 4 leaves
40.486553934113665: customer 6 enters
41.168084930967424: customer 5 leaves
45.72670063299798: customer 6 leaves
46.747675912143016: customer 7 enters
49.212327970772435: customer 8 enters
50.556538752352886: customer 9 enters
51.46738784004611: customer 8 leaves
52.514846525674855: customer 7 leaves
56.11635302397275: customer 9 leaves
>