Add Docs, triggered is processed now

Author: BenLauwens

docs/src/guides/basics.md

@@ -14,7 +14,7 @@ The environment stores these events in its event list and keeps track of the cur
 
 If a process function yields an event, SimJulia adds the process to the event’s callbacks and suspends the process until the event is triggered and processed. When a process waiting for an event is resumed, it will also receive the event’s value.
 
-Here is a very simple example that illustrates all this; the code is more verbose than it needs to be to make things extra clear. You find a compact version of it at the end of this section:
+Here is a very simple example that illustrates all this:
 
 ```jldoctest
 using ResumableFunctions
@@ -45,5 +45,5 @@ If all required process functions are defined, you can instantiate all objects f
 
 Starting a process function involves two things:
 
-- You have to call the macro `@process` with as argument a function call to the process function. (This will not execute any code of that function yet.) This will schedule an initialisation event at the current simulation time which starts the execution of the process function. The process instance is also an event that is triggered when the process function returns.
+- You have to call the macro `@process` with as argument a call to the process function. (This will not execute any code of that function yet.) This will schedule an initialisation event at the current simulation time which starts the execution of the process function. The process instance is also an event that is triggered when the process function returns.
 - Finally, you can start SimJulia’s event loop. By default, it will run as long as there are events in the event list, but you can also let it stop earlier by providing an until argument.

docs/src/guides/events.md

@@ -1 +1,61 @@
 # Events
+
+SimJulia includes an extensive set of event types for various purposes. All of them are descendants of `AbstractEvent`. Here the following events are discussed:
+
+- `Event`
+- `Timeout`
+- `Operator`
+
+The guide to resources describes the various resource events.
+
+## Event basics
+
+SimJulia events are very similar – if not identical — to deferreds, futures or promises. Instances of the type AbstractEvent are used to describe any kind of events. Events can be in one of the following states. An event:
+
+- might happen (idle),
+- is going to happen (scheduled) or
+- has happened (processed).
+
+They traverse these states exactly once in that order. Events are also tightly bound to time and time causes events to advance their state.
+
+Initially, events are idle and the function `state` returns `SimJulia.idle`.
+
+If an event gets scheduled at a given time, it is inserted into SimJulia’s event queue. The function `state` returns `SimJulia.scheduled`.
+
+As long as the event is not processed, you can add callbacks to an event. Callbacks are function having an `AbstractEvent` as first parameter.
+
+An event becomes processed when SimJulia pops it from the event queue and calls all of its callbacks. It is now no longer possible to add callbacks. The function `state` returns `SimJulia.processed`.
+
+Events also have a value. The value can be set before or when the event is scheduled and can be retrieved via the function `value` or, within a process, by yielding the event (`value = @yield event`).
+
+## Adding callbacks to an event
+
+“What? Callbacks? I’ve never seen no callbacks!”, you might think if you have worked your way through the tutorial.
+
+That’s on purpose. The most common way to add a callback to an event is yielding it from your process function (`@yield event`). This will add the process’ `resume` function as a callback. That’s how your process gets resumed when it yielded an event.
+
+However, you can add any function to the list of callbacks as long as it accepts `AbstractEvent` or a descendant as first parameter:
+
+```jldoctest
+julia> using SimJulia
+
+julia> function my_callback(ev::AbstractEvent)
+         println("Called back from ", ev)
+       end
+my_callback (generic function with 1 method)
+
+julia> sim = Simulation()
+SimJulia.Simulation time: 0.0 active_process: nothing
+
+julia> ev = Event(sim)
+SimJulia.Event 1
+
+julia> @callback my_callback(ev)
+(::#3) (generic function with 1 method)
+
+julia> succeed(ev)
+SimJulia.Event 1
+
+julia> run(sim)
+Called back from SimJulia.Event 1
+```

docs/src/index.md

@@ -2,7 +2,7 @@
 
 SimJulia is a discrete-event process-oriented simulation framework written in [Julia](http://julialang.org/) inspired by the Python library [SimPy](https://simpy.readthedocs.io/). Its process dispatcher is based on semi-coroutines scheduling as implemented in [ResumableFunctions](https://github.com/BenLauwens/ResumableFunctions.jl.git). A `Process` in SimJulia is defined by a `@resumable function` yielding `Events`. SimJulia provides three types of shared resources to model limited capacity congestion points: `Resources`, `Containers` and `Stores`. The API is modeled after the SimPy API but some specific Julia semantics are used.
 
-The documentation contains a tutorial, topical guides explaining key concepts, a number of examples and the API reference. The tutorial, the topical guides and some examples are borrowed from the SimPy to allow a direct comparison and an easy migration path for users. The differences between SimJulia and SimPy are clearly documented.
+The documentation contains a tutorial, topical guides explaining key concepts, a number of examples and the API reference. The tutorial, the topical guides and some examples are borrowed from SimPy to allow a direct comparison and an easy migration path for users. The differences between SimJulia and SimPy are clearly documented.
 
 ## Example
 

src/base.jl

@@ -1,9 +1,9 @@
 abstract type AbstractEvent end
 abstract type Environment end
 
-@enum EVENT_STATE idle=0 scheduled=1 triggered=2
+@enum EVENT_STATE idle=0 scheduled=1 processed=2
 
-struct EventTriggered <: Exception
+struct EventProcessed <: Exception
   ev :: AbstractEvent
 end
 
@@ -44,7 +44,7 @@ function state(ev::AbstractEvent) :: EVENT_STATE
 end
 
 function append_callback(func::Function, ev::AbstractEvent, args::Any...) :: Function
-  ev.bev.state == triggered && throw(EventTriggered(ev))
+  ev.bev.state == processed && throw(EventProcessed(ev))
   cb = ()->func(ev, args...)
   push!(ev.bev.callbacks, cb)
   cb

src/events.jl

@@ -7,7 +7,7 @@ end
 
 function succeed(ev::Event; priority::Int8=zero(Int8), value::Any=nothing) :: Event
   sta = state(ev)
-  (sta == scheduled || sta == triggered) && throw(EventNotIdle(ev))
+  (sta == scheduled || sta == processed) && throw(EventNotIdle(ev))
   schedule(ev; priority=priority, value=value)
   ev
 end

src/old/processes.jl

@@ -39,7 +39,7 @@ end
 function yield(target::AbstractEvent)
   env = environment(target)
   proc = active_process(env)
-  proc.target = state(target) == triggered ? Timeout(env; value=value(target)) : target
+  proc.target = state(target) == processed ? Timeout(env; value=value(target)) : target
   proc.resume = @callback execute(proc.target, proc)
   ret = SimJulia.produce(nothing)
   isa(ret, Exception) && throw(ret)

src/operators.jl

@@ -40,11 +40,11 @@ function check(ev::AbstractEvent, op::Operator, event_state_values::Dict{Abstrac
 end
 
 function eval_and(state_values::Vector{StateValue})
-  all(map((sv)->sv.state == triggered, state_values))
+  all(map((sv)->sv.state == processed, state_values))
 end
 
 function eval_or(state_values::Vector{StateValue})
-  any(map((sv)->sv.state == triggered, state_values))
+  any(map((sv)->sv.state == processed, state_values))
 end
 
 function (&)(ev1::AbstractEvent, ev2::AbstractEvent)

src/processes.jl

@@ -29,7 +29,7 @@ function execute(ev::AbstractEvent, proc::Process)
     if done(proc.fsm)
       schedule(proc; value=target)
     else
-      proc.target = state(target) == triggered ? Timeout(env; value=value(target)) : target
+      proc.target = state(target) == processed ? Timeout(env; value=value(target)) : target
       proc.resume = @callback execute(proc.target, proc)
     end
   catch exc

src/resources/containers.jl

@@ -39,7 +39,7 @@ function request(func::Function, res::Resource; priority::Int=0)
   try
     func(req)
   finally
-    if state(req) == triggered
+    if state(req) == processed
       yield(Release(res; priority=priority))
     else
       cancel(res, req)

src/simulations.jl

@@ -34,7 +34,7 @@ function step(sim::Simulation)
   (bev, key) = DataStructures.peek(sim.heap)
   DataStructures.dequeue!(sim.heap)
   sim.time = key.time
-  bev.state = triggered
+  bev.state = processed
   for callback in bev.callbacks
     callback()
   end