Docs added, @append_callback optimised

Author: BenLauwens

docs/make.jl

@@ -9,7 +9,8 @@ makedocs(
   pages    = [
     "Home" => "index.md",
     "Tutorial" => "tutorial.md",
-    "Topical Guides" => ["Basics" => "guides/basics.md",],
+    "Topical Guides" => ["Basics" => "guides/basics.md",
+                         "Environments" => "guides/environments.md",],
     "Examples" => ["Ross" => "examples/ross.md",],
     "API" => "api.md"
   ]

docs/src/examples/ross.md

@@ -30,35 +30,26 @@ srand(SEED)
 const F = Exponential(LAMBDA)
 const G = Exponential(MU)
 
-@resumable function machine(sim::Simulation, repair_facility::Resource, spares::Store{Process})
+@resumable function machine(env::Environment, repair_facility::Resource, spares::Store{Process})
     while true
-        try
-            @yield Timeout(sim, Inf)
-        catch exc
-        end
-        @yield Timeout(sim, rand(F))
+        try @yield Timeout(env, Inf) end
+        @yield Timeout(env, rand(F))
         get_spare = Get(spares)
-        @yield get_spare | Timeout(sim, 0.0)
+        @yield get_spare | Timeout(env)
         state(get_spare) != SimJulia.idle ? interrupt(value(get_spare)) : throw(SimJulia.StopSimulation("No more spares!"))
         @yield Request(repair_facility)
-        @yield Timeout(sim, rand(G))
+        @yield Timeout(env, rand(G))
         @yield Release(repair_facility)
-        @yield Put(spares, active_process(sim))
+        @yield Put(spares, active_process(env))
     end
 end
 
-@resumable function start_sim(sim::Simulation, repair_facility::Resource, spares::Store{Process})
+@resumable function start_sim(env::Environment, repair_facility::Resource, spares::Store{Process})
     procs = Process[]
-    for i=1:N
-        push!(procs, @process machine(sim, repair_facility, spares))
-    end
-    @yield Timeout(sim, 0.0)
-    for proc in procs
-        interrupt(proc)
-    end
-    for i=1:S
-        @yield Put(spares, @process machine(sim, repair_facility, spares))
-    end
+    for i in 1:N push!(procs, @process machine(env, repair_facility, spares)) end
+    @yield Timeout(env)
+    for proc in procs interrupt(proc) end
+    for i in 1:S @yield Put(spares, @process machine(env, repair_facility, spares)) end
 end
 
 function sim_repair()
@@ -73,9 +64,7 @@ function sim_repair()
 end
 
 results = Float64[]
-for i=1:RUNS
-    push!(results, sim_repair())
-end
+for i in 1:RUNS push!(results, sim_repair()) end
 println("Average crash time: ", sum(results)/RUNS)
 
 # output

docs/src/guides/basics.md

@@ -41,7 +41,7 @@ The process function then yields the event and thus gets suspended. It is resume
 
 Finally, the process function prints the current simulation time (that is accessible via the `now` function) and the `Timeout`’s value.
 
-If all required process functions are defined, you can instantiate all objects for your simulation. In most cases, you start by creating an instance of `Environement`, e.g. a `Simulation`, because you’ll need to pass it around a lot when creating everything else.
+If all required process functions are defined, you can instantiate all objects for your simulation. In most cases, you start by creating an instance of `Environment`, e.g. a `Simulation`, because you’ll need to pass it around a lot when creating everything else.
 
 Starting a process function involves two things:
 

docs/src/guides/environments.md

@@ -0,0 +1,77 @@
+# Environments
+
+A simulation environment manages the simulation time as well as the scheduling and processing of events. It also provides means to step through or execute the simulation.
+
+The base type for all environments is `Environment`. “Normal” simulations use its subtype `Simulation`.
+
+## Simulation control
+
+SimJulia is very flexible in terms of simulation execution. You can run your simulation until there are no more events, until a certain simulation time is reached, or until a certain event is triggered. You can also step through the simulation event by event. Furthermore, you can mix these things as you like.
+
+For example, you could run your simulation until an interesting event occurs. You could then step through the simulation event by event for a while; and finally run the simulation until there are no more events left and your processes have all terminated.
+
+The most important function here is `run`:
+
+- If you call it with an instance of the environment as the only argument  (`run(env)`), it steps through the simulation until there are no more events left. If your processes run forever, this function will never terminate (unless you kill your script by e.g., pressing `Ctrl-C`).
+
+- In most cases it is advisable to stop your simulation when it reaches a certain simulation time. Therefore, you can pass the desired time via a second argument, e.g.: `run(env, 10)`.
+
+  The simulation will then stop when the internal clock reaches 10 but will not process any events scheduled for time 10. This is similar to a new environment where the clock is 0 but (obviously) no events have yet been processed.
+
+  If you want to integrate your simulation in a GUI and want to draw a process bar, you can repeatedly call this function with increasing until values and update your progress bar after each call:
+
+```julia
+sim = Simulation()
+for t in 1:100
+  run(sim, t)
+  update(progressbar, t)
+end
+```
+
+- Instead of passing a number as second argument to `run`, you can also pass any event to it. `run` will then return when the event has been processed.
+
+  Assuming that the current time is 0, `run(env, Timeout(env, 5))` is equivalent to `run(env, 5)`.
+
+  You can also pass other types of events (remember, that a `Process` is an event, too):
+
+```jldoctest
+using ResumableFunctions
+using SimJulia
+
+@resumable function my_process(env::Environment)
+  @yield Timeout(env, 1)
+  "Monty Python's Flying Circus"
+end
+
+sim = Simulation()
+proc = @process my_process(sim)
+run(sim, proc)
+
+# output
+
+"Monty Python's Flying Circus"
+```
+
+To step through the simulation event by event, the environment offers `step`. This function processes the next scheduled event. It raises an `EmptySchedule` exception if no event is available.
+
+In a typical use case, you use this function in a loop like:
+```julia
+while now(sim) < 10
+  step(sim)
+end
+```
+
+## State access
+
+The environment allows you to get the current simulation time via the function `now`. The simulation time is a number without unit and is increased via `Timeout` events.
+
+By default, the simulation starts at time 0, but you can pass an `initial_time` to the `Simulation` constructor to use something else.
+
+Note
+
+!!! note
+    Although the simulation time is technically unitless, you can pretend that it is, for example, in milliseconds and use it like a timestamp returned by `Base.Dates.datetime2epochm` to calculate a date or the day of the week. The `Simulation` constructor and the `run` function accept as argument a `Base.Dates.DateTime` and the `Timeout` constructor a `Base.Dates.Delay`. Together with the convenience function `nowDateTime` a simulation can transparantly schedule its events in seconds, minutes, hours, days, ...
+
+The function `active_process` is comparable to `Base.Libc.getpid` and returns the current active `Process`. If no process is active, a `NullException` is thrown. A process is active when its process function is being executed. It becomes inactive (or suspended) when it yields an event.
+
+Thus, it only makes sense to call this function from within a process function or a function that is called by your process function:

src/SimJulia.jl

@@ -15,11 +15,11 @@ module SimJulia
   export AbstractEvent, Environment, value, state, environment
   export Event, Timeout, succeed, fail, @callback, remove_callback
   export Operator, (&), (|)
-  export Simulation, run, now, active_process
+  export AbstractProcess, Simulation, run, now, active_process
   export Process, @process, interrupt
-  export Container, Resource, Store, Put, Get, Request, Release, cancel, request, @request
+  export Container, Resource, Store, Put, Get, Request, Release, cancel
   export nowDatetime
-  export OldProcess, @oldprocess, yield
+  export OldProcess, @oldprocess, yield, request
 
   include("base.jl")
   include("events.jl")

src/base.jl

@@ -47,9 +47,7 @@ end
 
 macro callback(expr::Expr)
   expr.head != :call && error("Expression is not a function call!")
-  func = esc(expr.args[1])
-  args = [esc(expr.args[n]) for n in 2:length(expr.args)]
-  :(append_callback($(func), $(args...)))
+  esc(:(SimJulia.append_callback($(expr.args...))))
 end
 
 function remove_callback(cb::Function, ev::AbstractEvent)