Add Docs and show methods

Author: BenLauwens

docs/make.jl

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

docs/src/guides/environments.md

@@ -74,4 +74,64 @@ Note
 
 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:
+Thus, it only makes sense to call this function from within a process function or a function that is called by your process function:
+
+```jldoctest
+julia> using ResumableFunctions
+
+julia> using SimJulia
+
+julia> function subfunc(env::Environment)
+         println(active_process(env))
+       end
+subfunc (generic function with 1 method)
+
+julia> @resumable function my_proc(env::Environment)
+         while true
+           println(active_process(env))
+           subfunc(env)
+           @yield Timeout(env, 1)
+         end
+       end
+my_proc (generic function with 1 method)
+
+julia> sim = Simulation()
+SimJulia.Simulation time: 0.0 active_process: nothing
+
+julia> @process my_proc(sim)
+SimJulia.Process 1
+
+julia> active_process(sim)
+ERROR: NullException()
+[...]
+
+julia> SimJulia.step(sim)
+SimJulia.Process 1
+SimJulia.Process 1
+
+julia> active_process(sim)
+ERROR: NullException()
+[...]
+```
+
+An exemplary use case for this is the resource system: If a process function calls `request` to request a `Resource`, the resource determines the requesting process via `active_process`.
+
+## Miscellaneous
+
+A generator function can have a return value:
+
+```julia
+@resumable function my_proc(env::Environment)
+  @yield Timeout(sim, 1)
+  150
+end
+```
+
+In SimJulia, this can be used to provide return values for processes that can be used by other processes:
+
+```julia
+@resumable function other_proc(env::Environment)
+  ret_val = @yield @process my_proc(env)
+  @assert ret_val == 150
+end
+```

docs/src/guides/events.md

@@ -0,0 +1 @@
+# Events

docs/src/index.md

@@ -22,7 +22,7 @@ julia> @resumable function clock(sim::Simulation, name::String, tick::Float64)
 clock (generic function with 1 method)
 
 julia> sim = Simulation()
-SimJulia.Simulation(0.0, DataStructures.PriorityQueue{SimJulia.BaseEvent,SimJulia.EventKey,Base.Order.ForwardOrdering}(), 0x0000000000000000, 0x0000000000000000, Nullable{SimJulia.AbstractProcess}())
+SimJulia.Simulation time: 0.0 active_process: nothing
 
 julia> @process clock(sim, "fast", 0.5)
 SimJulia.Process 1

docs/src/tutorial.md

@@ -59,7 +59,7 @@ end
 
 ```jldoctest
 julia> sim = Simulation()
-SimJulia.Simulation(0.0, DataStructures.PriorityQueue{SimJulia.BaseEvent,SimJulia.EventKey,Base.Order.ForwardOrdering}(), 0x0000000000000000, 0x0000000000000000, Nullable{SimJulia.AbstractProcess}())
+SimJulia.Simulation time: 0.0 active_process: nothing
 
 julia> @process car(sim)
 SimJulia.Process 1
@@ -150,7 +150,7 @@ Starting the simulation is straightforward again: We create a `Simulation`, one
 
 ```jldoctest
 julia> sim = Simulation()
-SimJulia.Simulation(0.0, DataStructures.PriorityQueue{SimJulia.BaseEvent,SimJulia.EventKey,Base.Order.ForwardOrdering}(), 0x0000000000000000, 0x0000000000000000, Nullable{SimJulia.AbstractProcess}())
+SimJulia.Simulation time: 0.0 active_process: nothing
 
 julia> @process car(sim)
 SimJulia.Process 1
@@ -256,7 +256,7 @@ end
 
 ```jldoctest
 julia> sim = Simulation()
-SimJulia.Simulation(0.0, DataStructures.PriorityQueue{SimJulia.BaseEvent,SimJulia.EventKey,Base.Order.ForwardOrdering}(), 0x0000000000000000, 0x0000000000000000, Nullable{SimJulia.AbstractProcess}())
+SimJulia.Simulation time: 0.0 active_process: nothing
 
 julia> car_process = @process car(sim)
 SimJulia.Process 1
@@ -331,10 +331,10 @@ end
 
 ```jldoctest
 julia> sim = Simulation()
-SimJulia.Simulation(0.0, DataStructures.PriorityQueue{SimJulia.BaseEvent,SimJulia.EventKey,Base.Order.ForwardOrdering}(), 0x0000000000000000, 0x0000000000000000, Nullable{SimJulia.AbstractProcess}())
+SimJulia.Simulation time: 0.0 active_process: nothing
 
 julia> bcs = Resource(sim, 2)
-SimJulia.Container{Int64}(SimJulia.Simulation(0.0, DataStructures.PriorityQueue{SimJulia.BaseEvent,SimJulia.EventKey,Base.Order.ForwardOrdering}(), 0x0000000000000000, 0x0000000000000000, Nullable{SimJulia.AbstractProcess}()), 2, 0, 0x0000000000000000, DataStructures.PriorityQueue{SimJulia.Put,SimJulia.ContainerKey{Int64},Base.Order.ForwardOrdering}(), DataStructures.PriorityQueue{SimJulia.Get,SimJulia.ContainerKey{Int64},Base.Order.ForwardOrdering}())
+SimJulia.Container{Int64}
 ```
 
 We can now create the car processes and pass a reference to our resource as well as some additional parameters to them

src/base.jl

@@ -26,6 +26,11 @@ function show(io::IO, ev::AbstractEvent)
   print(io, "$(typeof(ev)) $(ev.bev.id)")
 end
 
+function show(io::IO, env::Environment)
+  active_proc = try get(sim.active_proc) catch; nothing end
+  print(io, "$(typeof(env)) time: $(now(env)) active_process: $(active_proc)")
+end
+
 function environment(ev::AbstractEvent) :: Environment
   ev.bev.env
 end

src/resources/base.jl

@@ -2,6 +2,10 @@ abstract type ResourceKey end
 
 abstract type AbstractResource end
 
+function show(io::IO, res::AbstractResource)
+  print(io, "$(typeof(res))")
+end
+
 abstract type ResourceEvent <: AbstractEvent end
 
 struct Put <: ResourceEvent

test/processes.jl

@@ -42,6 +42,7 @@ end
 
 sim = Simulation()
 @process fibonnaci(sim)
+println(sim)
 run(sim, 10)
 
 sim = Simulation()

test/resources/containers.jl

@@ -19,6 +19,7 @@ end
 
 sim = Simulation()
 res = Resource(sim, 2; level=1)
+println(res)
 @process generate(sim, res)
 run(sim)