documentation and doctests

Author: Krastanov

CHANGELOG.md

@@ -2,7 +2,8 @@
 
 ## v1.0.1 - dev
 
-- Start using `Base`'s API: `lock`, `trylock`, `unlock`, `islocked`, `isready`, `get!` and deprecate `get`, `request`, `release`.
+- Start using `Base`'s API: `lock`, `trylock`, `unlock`, `islocked`, `isready`, `put!`, `take!`. Deprecate `put`, `request`, `release`. Moreover, consider using `take!` instead of `get` (which was not deprecated as it has numerous internal uses).
+
 ## v1.0.0 - 2023-05-03
 
 - Rename from SimJulia.jl to ConcurrentSim.jl

docs/Project.toml

@@ -3,4 +3,5 @@ ConcurrentSim = "6ed1e86c-fcaf-46a9-97e0-2b26a2cdb499"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 ResumableFunctions = "c5292f4c-5179-55e1-98c5-05642aab7184"
+Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
 StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"

docs/make.jl

@@ -1,3 +1,4 @@
+using Revise
 using Documenter
 using ResumableFunctions
 using ConcurrentSim

docs/src/api.md

@@ -3,4 +3,11 @@
 ```@autodocs
 Modules = [ConcurrentSim]
 Private = false
+```
+
+```@docs
+lock(res::Container; priority::Int=0)
+unlock(res::Container; priority::Int=0)
+trylock(res::Container; priority::Int=0)
+take!(sto::Store, filter::Function=get_any_item; priority::Int=0)
 ```

docs/src/examples/Latency.md

@@ -7,27 +7,32 @@ In this example we show how to separate the time delay between processes from th
 ### Load Packages
 
 
-```julia
+```jldoctest 1; output = false
 using ConcurrentSim
 using ResumableFunctions
-import Base: put!, get
+import Base: put!, take!
+
+# output
 ```
 
 ### Define Constants
 
 
-```julia
-srand(8710) # set random number seed for reproducibility
+```jldoctest 1; output = false
 const SIM_DURATION = 100.
 const SEND_PERIOD = 5.0
 const RECEIVE_PERIOD = 3.0;
+
+nothing # hide
+
+# output
 ```
 
 ### Define Cable model
 The `Cable` contains reference to the simulation it is part of, the delay that messages experience, and a store that contains the sent messages
 
 
-```julia
+```jldoctest 1; output = false
 mutable struct Cable
     env::Simulation
     delay::Float64
@@ -37,35 +42,47 @@ mutable struct Cable
         return new(env, delay, Store{String}(env))
     end
 end;
+
+nothing # hide
+
+# output
 ```
 
 The latency function is a generator which yields two events: first a `timeout` that represents the transmission delay, then a put event when the message gets stored in the store.
 
 
-```julia
+```jldoctest 1; output = false
 @resumable function latency(env::Simulation, cable::Cable, value::String)
     @yield timeout(cable.env, cable.delay)
     @yield put!(cable.store, value)
-    end;
+end;
+
+nothing # hide
+
+# output
 ```
 
-The `put!` and `get` functions allow interaction with the cable (note that these are not `@resumable` because they need to return the result of the operation and not the operation itself).
+The `put!` and `take!` functions allow interaction with the cable (note that these are not `@resumable` because they need to return the result of the operation and not the operation itself).
 
 
-```julia
+```jldoctest 1; output = false 
 function put!(cable::Cable, value::String)
     @process latency(cable.env, cable, value) # results in the scheduling of all events generated by latency
 end
 
-function get(cable::Cable)
-    get(cable.store) # returns an element stored in the cable store
+function take!(cable::Cable); output = false
+    take!(cable.store) # returns an element stored in the cable store
 end;
+
+nothing # hide
+
+# output
 ```
 
 The `sender` and `receiver` generators yield events to the simulator.
 
 
-```julia
+```jldoctest 1; output = false
 @resumable function sender(env::Simulation, cable::Cable)
     while true
         @yield timeout(env, SEND_PERIOD)
@@ -77,39 +94,44 @@ end
 @resumable function receiver(env::Simulation, cable::Cable)
     while true
         @yield timeout(env, RECEIVE_PERIOD)
-        msg = @yield get(cable)
+        msg = @yield take!(cable)
         println("Received this at $(now(env)) while $msg")
     end
 end;
+
+nothing # hide
+
+# output
 ```
 
 Create simulation, register events, and run!
 
 
-```julia
+```jldoctest 1
 env = Simulation()
 cable = Cable(env, 10.)
 @process sender(env, cable)
 @process receiver(env, cable)
 
 run(env, SIM_DURATION)
-```
-
-    Received this at 15.0 while sender sent this at 5.0
-    Received this at 20.0 while sender sent this at 10.0
-    Received this at 25.0 while sender sent this at 15.0
-    Received this at 30.0 while sender sent this at 20.0
-    Received this at 35.0 while sender sent this at 25.0
-    Received this at 40.0 while sender sent this at 30.0
-    Received this at 45.0 while sender sent this at 35.0
-    Received this at 50.0 while sender sent this at 40.0
-    Received this at 55.0 while sender sent this at 45.0
-    Received this at 60.0 while sender sent this at 50.0
-    Received this at 65.0 while sender sent this at 55.0
-    Received this at 70.0 while sender sent this at 60.0
-    Received this at 75.0 while sender sent this at 65.0
-    Received this at 80.0 while sender sent this at 70.0
-    Received this at 85.0 while sender sent this at 75.0
-    Received this at 90.0 while sender sent this at 80.0
-    Received this at 95.0 while sender sent this at 85.0
 
+# output
+
+Received this at 15.0 while sender sent this at 5.0
+Received this at 20.0 while sender sent this at 10.0
+Received this at 25.0 while sender sent this at 15.0
+Received this at 30.0 while sender sent this at 20.0
+Received this at 35.0 while sender sent this at 25.0
+Received this at 40.0 while sender sent this at 30.0
+Received this at 45.0 while sender sent this at 35.0
+Received this at 50.0 while sender sent this at 40.0
+Received this at 55.0 while sender sent this at 45.0
+Received this at 60.0 while sender sent this at 50.0
+Received this at 65.0 while sender sent this at 55.0
+Received this at 70.0 while sender sent this at 60.0
+Received this at 75.0 while sender sent this at 65.0
+Received this at 80.0 while sender sent this at 70.0
+Received this at 85.0 while sender sent this at 75.0
+Received this at 90.0 while sender sent this at 80.0
+Received this at 95.0 while sender sent this at 85.0
+```

docs/src/examples/ross.md

@@ -37,7 +37,7 @@ const G = Exponential(MU)
     while true
         try @yield timeout(env, Inf) catch end
         @yield timeout(env, rand(rng, F))
-        get_spare = get(spares)
+        get_spare = take!(spares)
         @yield get_spare | timeout(env)
         if state(get_spare) != ConcurrentSim.idle 
             @yield interrupt(value(get_spare))

src/resources/containers.jl

@@ -4,6 +4,21 @@ struct ContainerKey{N<:Real} <: ResourceKey
   amount :: N
 end
 
+"""
+    Container{N}(env::Environment, capacity::N=one(N); level::N=zero(N))
+
+A "Container" resource object, storing up to `capacity` units of a resource (of type `N`).
+
+There is a `Resource` alias for `Container{Int}`.
+
+`Resource()` with default capacity of `1` is very similar to a typical lock.
+The [`lock`](@ref), [`unlock`](@ref), and [`trylock`](@ref) functions are a convenient way to interact with such a "lock",
+in a way mostly compatible with other discrete event and concurrency frameworks.
+
+See [`Store`](@ref) for a more channel-like resource.
+
+Think of `Resource` and `Container` as locks and of `Store` as channels. They block only if empty (on taking) or full (on storing).
+"""
 mutable struct Container{N<:Real} <: AbstractResource
   env :: Environment
   capacity :: N
@@ -30,7 +45,12 @@ function put!(con::Container{N}, amount::N; priority::Int=0) where N<:Real
   put_ev
 end
 
-lock(res::Resource; priority::Int=0) = put!(res, 1; priority=priority)
+"""
+    lock(res::Container)
+
+Locks the Container and return the lock event.
+"""
+lock(res::Container; priority::Int=0) = put!(res, 1; priority=priority)
 
 """
     trylock(res::Resource)
@@ -51,7 +71,7 @@ julia> trylock(res)
 false
 ```
 """
-function trylock(res::Resource; priority::Int=0)
+function trylock(res::Container; priority::Int=0)
     islocked(res) && return false # TODO check priority
     lock(res; priority)
 end
@@ -64,7 +84,12 @@ function get(con::Container{N}, amount::N; priority::Int=0) where N<:Real
   get_ev
 end
 
-unlock(res::Resource; priority::Int=0) = get(res, 1; priority=priority)
+"""
+    unlock(res::Container)
+
+Unlocks the Container and return the unlock event.
+"""
+unlock(res::Container; priority::Int=0) = get(res, 1; priority=priority)
 
 function do_put(con::Container{N}, put_ev::Put, key::ContainerKey{N}) where N<:Real
   con.level + key.amount > con.capacity && return false

src/resources/stores.jl

@@ -11,6 +11,16 @@ struct StoreGetKey <: ResourceKey
   filter :: Function
 end
 
+"""
+    Store{T}(env::Environment; capacity::UInt=typemax(UInt))
+
+A store is a resource that can hold a number of items of type `T`. It is similar to a `Base.Channel` with a finite capacity ([`put!`](@ref) blocks after reaching capacity).
+The [`put!`](@ref) and [`take!`](@ref) functions are a convenient way to interact with such a "channel" in a way mostly compatible with other discrete event and concurrency frameworks.
+
+See [`Container`](@ref) for a more lock-like resource.
+
+Think of `Resource` and `Container` as locks and of `Store` as channels. They block only if empty (on taking) or full (on storing).
+"""
 mutable struct Store{T} <: AbstractResource
   env :: Environment
   capacity :: UInt
@@ -24,6 +34,11 @@ mutable struct Store{T} <: AbstractResource
   end
 end
 
+"""
+    put!(sto::Store, item::T)
+
+Put an item into the store. Returns the put event, blocking if the store is full.
+"""
 function put!(sto::Store{T}, item::T; priority::Int=0) where T
   put_ev = Put(sto.env)
   sto.put_queue[put_ev] = StorePutKey{T}(priority, sto.seid+=one(UInt), item)
@@ -100,13 +115,13 @@ true
 """
 islocked(sto::Store) = sto.load==sto.capacity
 
-unlock(::Store) = error("There is no well defined way to \"unlock\" a store. Instead of attempting `unlock` consider using `pop!(::Store)` or use a `Resource` instead of a `Store`.")
-lock(::Store) = error("There is no well defined way to \"lock\" a store. Instead of attempting `lock` consider using `put!(::Store, ...)` or use a `Resource` instead of a `Store`.")
-trylock(::Store) = error("There is no well defined way to \"lock\" a store. Instead of attempting `lock` consider using `put!(::Store, ...)` or use a `Resource` instead of a `Store`.")
+unlock(::Store) = error("There is no well defined way to \"unlock\" a Store without taking an element out of it. Instead of attempting `unlock` consider using `take!(::Store)` or use a `Resource` instead of a `Store`. Think of `Resource` and `Container` as locks and of `Store` as channels. They block only if empty (on taking) or full (on storing).")
+lock(::Store) = error("There is no well defined way to \"lock\" a Store without storing an element in it. Instead of attempting `lock` consider using `put!(::Store, ...)` or use a `Resource` instead of a `Store`. Think of `Resource` and `Container` as locks and of `Store` as channels. They block only if empty (on taking) or full (on storing).")
+trylock(::Store) = error("There is no well defined way to \"lock\" a Store without storing an element in it. Instead of attempting `lock` consider using `put!(::Store, ...)` or use a `Resource` instead of a `Store`. Think of `Resource` and `Container` as locks and of `Store` as channels. They block only if empty (on taking) or full (on storing).")
 
 """
     take!(::Store)
 
 An alias for `get(::Store)` for easier interoperability with the `Base.Channel` interface. Blocks if the store is empty.
 """
-take!(sto::Store{T}, filter::Function=get_any_item; priority::Int=0) where {T} = get(sto, filter; priority)
+take!(sto::Store, filter::Function=get_any_item; priority::Int=0) = get(sto, filter; priority)