Merge pull request #93 from JuliaDynamics/convenienceinterfaces

introduce unlock, islocked, isready, get! and deprecate get, release

Author: Krastanov

CHANGELOG.md

@@ -1,5 +1,10 @@
 # News
 
+## v1.1.0 - 2023-08-02
+
+- Start using `Base`'s API: `Base.unlock`, `Base.islocked`, `Base.isready`, `Base.put!`, `Base.take!`. Deprecate `put`, `release`. Moreover, consider using `Base.take!` instead of `Base.get` (which was not deprecated yet, as we decide which semantics to follow). Lastly, `Base.lock` and `Base.trylock` are **not** implement -- they are superficially similar to `request` and `tryrequest`, but have to be explicitly `@yield`-ed.
+- Implement `tryrequest` (similar to `Base.trylock`). However, consider also using `Base.isready` and `request` instead of `tryrequest`.
+
 ## v1.0.0 - 2023-05-03
 
 - Rename from SimJulia.jl to ConcurrentSim.jl

Project.toml

@@ -5,7 +5,7 @@ license = "MIT"
 desc = "A discrete event process oriented simulation framework."
 authors = ["Ben Lauwens and SimJulia and ConcurrentSim contributors"]
 repo = "https://github.com/JuliaDynamics/ConcurrentSim.jl.git"
-version = "1.0.0"
+version = "1.1.0"
 
 [deps]
 DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"

benchmark/old_processes_MM1.jl

@@ -12,7 +12,7 @@ function customer(sim::Simulation, server::Resource, mu::Float64)
   yield(request(server))
   dt = rand(Exponential(1/mu))
   yield(timeout(sim, dt))
-  yield(release(server))
+  yield(unlock(server))
 end
 
 function customer2(sim::Simulation, server::Resource, mu::Float64)

benchmark/processes_MM1.jl

@@ -12,7 +12,7 @@ end
   @yield request(server)
   dt = rand(Exponential(1 / mu))
   @yield timeout(sim, dt)
-  @yield release(server)
+  @yield unlock(server)
 end
 
 function test_mm1(n::Float64)

docs/Project.toml

@@ -1,3 +1,7 @@
 [deps]
+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,10 +1,15 @@
+using Revise
 using Documenter
 using ResumableFunctions
 using ConcurrentSim
 
+DocMeta.setdocmeta!(ConcurrentSim, :DocTestSetup, :(using ConcurrentSim, ResumableFunctions); recursive=true)
+
 makedocs(
   sitename = "ConcurrentSim",
   authors = "Ben Lauwens and SimJulia & ConcurrentSim contributors",
+  strict = true,
+  doctest = false,
   pages    = [
     "Home" => "index.md",
     "Tutorial" => "tutorial.md",

docs/src/api.md

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

docs/src/examples/Latency.md

@@ -7,28 +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  ConcurrentSim.put
-import Base.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
@@ -38,79 +42,96 @@ 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;
+    @yield put!(cable.store, value)
+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
-function put(cable::Cable, value::String)
+```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)
         value = "sender sent this at $(now(env))"
-        put(cable, value)
+        put!(cable, value)
     end
 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/mmc.md

@@ -25,7 +25,7 @@ service_dist = Exponential(1 / mu) # service time distribution
     @yield request(server) # customer starts service
     println("Customer $id entered service: ", now(env))
     @yield timeout(env, rand(d_s)) # server is busy
-    @yield release(server) # customer exits service
+    @yield unlock(server) # customer exits service
     println("Customer $id exited service: ", now(env))
 end
 

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))
@@ -46,8 +46,8 @@ const G = Exponential(MU)
         end
         @yield request(repair_facility)
         @yield timeout(env, rand(rng, G))
-        @yield release(repair_facility)
-        @yield put(spares, active_process(env))
+        @yield unlock(repair_facility)
+        @yield put!(spares, active_process(env))
     end
 end
 
@@ -58,7 +58,7 @@ end
     end
     for i in 1:S
         proc = @process machine(env, repair_facility, spares)
-        @yield put(spares, proc) 
+        @yield put!(spares, proc) 
     end
 end