simplekit 0.4.5 → 1.0.0

data/demos/MMk_shutdown.rb

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/simplekit'
+
+# Demonstration model of an M/M/k queueing system.  There are k servers
+# and both the arrival and service processes are memoryless (exponential).
+class MMk
+  include SimpleKit
+
+  # Constructor - initializes the model parameters.
+  # param: arrival_rate - The rate at which customers arrive to the system.
+  # param: service_rate - The rate at which individual servers serve.
+  # param: max_servers - The total number of servers in the system.
+  def initialize(arrival_rate, service_rate, max_servers)
+    @arrival_rate = arrival_rate
+    @service_rate = service_rate
+    @max_servers = max_servers
+  end
+
+  # Initialize the model state and schedule any necessary events.
+  # Note that this particular model will terminate based on
+  # time by scheduling a halt 100 time units in the future.
+  def init
+    @num_available_servers = @max_servers
+    @q_length = 0
+    schedule(:arrival, 0.0)
+    schedule(:close_doors, 100.0)
+    dump_state('init')
+  end
+
+  # An arrival event increments the queue length, schedules the next
+  # arrival, and schedules a begin_service event if a server is available.
+  def arrival
+    @q_length += 1
+    schedule(:arrival, exponential(@arrival_rate))
+    schedule(:begin_service, 0.0) if @num_available_servers > 0
+    dump_state('arrival')
+  end
+
+  # Start service for the first customer in line, removing that
+  # customer from the queue and utilizing one of the available servers.
+  # An end_service will be scheduled.
+  def begin_service
+    @q_length -= 1
+    @num_available_servers -= 1
+    schedule(:end_service, exponential(@service_rate))
+    dump_state('begin svc')
+  end
+
+  # Frees up an available server, and schedules a begin_service if
+  # anybody is waiting in line.
+  def end_service
+    @num_available_servers += 1
+    schedule(:begin_service, 0.0) if @q_length > 0
+    dump_state('end svc')
+  end
+
+  def close_doors
+    cancel(:arrival)
+  end
+
+  # Exponential random variate generator.
+  # param: rate - The rate (= 1 / mean) of the distribution.
+  # returns: A realization of the specified distribution.
+  def exponential(rate)
+    -Math.log(rand) / rate
+  end
+
+  # A report mechanism which dumps the time, current event, and values
+  # of the state variables to the console.
+  # param: event - The name of the event which invoked this method.
+  def dump_state(event)
+    printf "Time: %8.3f\t%10s - Q: %d\tServers Available: %d\n",
+           model_time, event, @q_length, @num_available_servers
+  end
+end
+
+# Instantiate an MMk object with a particular parameterization and run it.
+srand 7_654_321
+MMk.new(4.5, 1.0, 5).run

data/demos/sptf.rb

@@ -0,0 +1,86 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/simplekit'
+
+# Create a Customer Struct that will store arrival times and processing times.
+Customer = Struct.new(:arrival_time, :processing_time) do
+  include Comparable
+  # rank customers by their processing times, smallest first.
+  def <=>(other)
+    processing_time <=> other.processing_time
+  end
+end
+
+# Demonstration model of a shortest-processing-time-first queueing system.
+# There are k servers and both the arrival and service processes could
+# be anything.
+class SPTF
+  include SimpleKit
+
+  # Constructor - initializes the model parameters.
+  # param: arrivalRate - The rate at which customers arrive to the system.
+  # param: serviceRate - The rate at which individual servers serve.
+  # param: maxServers - The total number of servers in the system.
+  # param: closeTime - The time the server would like to shut down.
+  def initialize(arrivalRate, serviceRate, maxServers, closeTime)
+    @arrivalRate = arrivalRate
+    @serviceRate = serviceRate
+    @maxServers = maxServers
+    @closeTime = closeTime
+  end
+
+  # Initialize the model state and schedule any necessary events.
+  def init
+    @numAvailableServers = @maxServers
+    @q = PriorityQueue.new
+    schedule(:arrival, 0.0)
+    schedule(:close_doors, @closeTime)
+  end
+
+
+  # An arrival event generates a customer and their associated service
+  # time, adds the customer to the queue, schedules the next arrival,
+  # and schedules a beginService event if a server is available.
+  def arrival
+    @q.push Customer.new(model_time, exponential(@serviceRate))
+    schedule(:arrival, exponential(@arrivalRate))
+    schedule(:beginService, 0.0) if (@numAvailableServers > 0)
+  end
+
+  # Start service for the first customer in line, removing that
+  # customer from the queue and utilizing one of the available
+  # servers.  An endService will be scheduled.  Report the current
+  # time and how long this customer spent in line.
+  def beginService
+    current_customer = @q.pop
+    @numAvailableServers -= 1
+    schedule(:endService, current_customer.processing_time)
+    printf "%f,%f\n", model_time, model_time - current_customer.arrival_time
+  end
+
+  # Frees up an available server, and schedules a beginService if
+  # anybody is waiting in line.  If the line is empty and it's after
+  # the desired closing time, halt the simulation.
+  def endService
+    @numAvailableServers += 1
+    unless @q.empty?
+      schedule(:beginService, 0.0)
+    end
+  end
+
+  # Commence shutdown by denying the next :arrival
+  def close_doors
+    cancel :arrival
+  end
+
+  # Exponential random variate generator.
+  # param: rate - The rate (= 1 / mean) of the distribution.
+  # returns: A realization of the specified distribution.
+  def exponential(rate)
+    -Math.log(rand) / rate
+  end
+end
+
+# Instantiate an SPTF object with a particular parameterization and run it.
+srand(9876543)  # set seed for repeatability
+SPTF.new(6, 1.0, 5, 20.0).run

data/lib/priority_queue.rb

@@ -4,6 +4,7 @@ class PriorityQueue
     clear
   end
 
+  # Push +element+ onto the priority queue.
   def <<(element)
     @elements << element
     # bubble up the element that we just added
@@ -12,11 +13,13 @@ class PriorityQueue
 
   alias push <<
 
+  # Inspect the element at the head of the queue.
   def peek
     # the first element will always be the min, because of the heap constraint
     @elements[1]
   end
 
+  # Remove and return the next element from the queue, determined by priority.
   def pop
     # remove the last element of the list
     min = @elements[1]
@@ -26,10 +29,12 @@ class PriorityQueue
     min
   end
 
+  # Reset the priority queue to empty.
   def clear
     @elements = [nil]
   end
 
+  # Return a boolean indicating whether the queue is empty or not
   def empty?
     @elements.length < 2
   end

data/lib/simplekit.rb

@@ -1,15 +1,18 @@
+require 'set'
 require_relative 'priority_queue'
 
 # The +SimpleKit+ module provides basic event scheduling capabilities.
 #
 # Including +SimpleKit+ in your simulation model gives you methods +:run+,
-# +:model_time+, +:schedule+, and +:halt+ as mixins.  You <b>MUST NOT</b>
-# provide your own implementations of methods with these names in your model.
-# All but +:run+ are delegated to the +EventScheduler+ class.
+# +:model_time+, +:schedule+, +:cancel+, +:cancel_all+, and +:halt+ as mixins.
+# <b>DO NOT</b> create your own implementations of methods with these names
+# in your model. All but +:run+ are delegated to the +EventScheduler+ class.
 module SimpleKit
   # The set of module methods to be passed to the EventScheduler
   # if not found in the model class.
-  DELEGATED_METHODS = [:model_time, :schedule, :halt].freeze
+  DELEGATED_METHODS = %i[
+    model_time schedule cancel cancel_all halt
+  ].freeze
 
   # Run your model by creating a new +EventScheduler+ and invoking its
   # +run+ method.
@@ -21,11 +24,7 @@ module SimpleKit
   # If a method doesn't exist in the model class, try to delegate it
   # to +EventScheduler+.
   def method_missing(name, *args)
-    if DELEGATED_METHODS.include?(name)
-      @my_sim.send(name, *args)
-    else
-      super
-    end
+    DELEGATED_METHODS.include?(name) ? @my_sim.send(name, *args) : super
   end
 
   # Class +EventScheduler+ provides the computation engine for a
@@ -43,6 +42,7 @@ module SimpleKit
     def initialize(the_model)
       @user_model = the_model
       @event_list = PriorityQueue.new
+      @cancel_set = {}
     end
 
     # Add an event to the pending events list.
@@ -51,24 +51,53 @@ module SimpleKit
     #   - +event+ -> the event to be scheduled.
     #   - +delay+ -> the amount of time which should elapse before
     #     the event executes.
-    #   - +args+ -> an optional list of arguments to pass to the event
-    #     at invocation time.
-    def schedule(event, delay, *args)
+    #   - +args+ -> zero or more named arguments to pass to the event
+    #     at invocation time. These should be specified with labels, and
+    #     consequently they can be placed in any order.
+    def schedule(event, delay, **args)
       raise 'Model scheduled event with negative delay.' if delay < 0
-      @event_list.push EventNotice.new(event, @model_time + delay, args)
+      @event_list.push EventNotice.new(event, @model_time, delay, args)
+    end
+
+    # Cancel an individual occurrence of event type +event+.
+    # If no +args+ are provided, the next scheduled occurrence of +event+
+    # is targeted.  If a subset of the event's +args+ is provided, they must
+    # all be a match with the corresponding +args+ of the scheduled event
+    # in order for the cancellation to apply, but +args+ which are not
+    # specified do not affect the target event matching.
+    def cancel(event, **args)
+      @cancel_set[event] ||= Set.new
+      @cancel_set[event].add(args.empty? ? nil : args)
+    end
+
+    # Cancel all currently scheduled events of type +event+.
+    def cancel_all(event)
+      if event
+        PriorityQueue.new.tap do |pq|
+          while (event_notice = @event_list.pop)
+            pq.push event_notice unless event_notice.event == event
+          end
+          @event_list = pq
+        end
+      end
     end
 
     # Start execution of a model. The simulation +model_time+ is initialized
     # to zero and the model is initialized via the mandatory +init+ method.
-    # Then loop while events are pending on the +event_list+. The event with
-    # the smallest time is popped, +model_time+ is updated to the event time,
-    # and the event method is invoked.
+    # Then loop while events are pending on the +event_list+. The event with the
+    # smallest time is popped, +model_time+ is updated to the event time, and
+    # the event method is invoked with the +args+, if any, set by +schedule+.
     def run
       @model_time = 0.0
       @user_model.init
       while (current_event = @event_list.pop)
+        next if should_cancel?(current_event)
         @model_time = current_event.time
-        @user_model.send(current_event.event, *current_event.args)
+        if current_event.args.empty?
+          @user_model.send(current_event.event)
+        else
+          @user_model.send(current_event.event, current_event.args)
+        end
       end
     end
 
@@ -77,14 +106,51 @@ module SimpleKit
     def halt
       @event_list.clear
     end
-  end
 
-  # This is a private helper Struct for the EventScheduler class.
-  # Users should never try to access this directly.
-  EventNotice = Struct.new(:event, :time, *:args) do
-    include Comparable
-    def <=>(other)
-      time <=> other.time
+    private
+
+    # Private method that returns a boolean to determine if +event_notice+
+    # represents an event subject to cancellation.
+    def should_cancel?(event_notice)
+      e = event_notice.event
+      if @cancel_set.key? e
+        if @cancel_set[e].include? nil
+          @cancel_set[e].delete nil
+          @cancel_set.delete e if @cancel_set[e].empty?
+          return true
+        else
+          for hsh in @cancel_set[e] do
+            next unless event_notice.args >= hsh
+            @cancel_set[e].delete hsh
+            @cancel_set.delete e if @cancel_set[e].empty?
+            return true
+          end
+        end
+      end
+      false
+    end
+
+    # This is a private helper class for the EventScheduler class.
+    # Users should never try to access this directly.
+    class EventNotice
+      attr_reader :event, :time, :time_stamp, :priority, :args
+
+      def initialize(event, time, delay, args)
+        @event = event
+        @time_stamp = time
+        @time = time + delay
+        @args = args
+        @priority = @args && @args.key?(:priority) ? @args.delete(:priority) : 10
+      end
+
+      include Comparable
+      # Compare EventNotice objects for ordering, first by time,
+      # breaking ties using priority.
+      def <=>(other)
+        (time <=> other.time).tap do |outcome|
+          return priority <=> other.priority if outcome == 0
+        end
+      end
     end
   end
 end

data/simplekit.gemspec

@@ -1,10 +1,10 @@
 # -*- ruby -*-
-_VERSION = "0.4.5"
+_VERSION = "1.0.0"
 
 Gem::Specification.new do |s|
   s.name = "simplekit"
   s.version = _VERSION
-  s.date = "2017-12-01"
+  s.date = "2018-07-12"
   s.summary = "Discrete event simulation engine."
   s.homepage = "https://gitlab.nps.edu/pjsanche/simplekit-ruby.git"
   s.email = "pjs@alum.mit.edu"
@@ -14,7 +14,12 @@ Gem::Specification.new do |s|
     simplekit.gemspec
     lib/simplekit.rb
     lib/priority_queue.rb
+    demos/MMk.rb
+    demos/MMk_reference_output.txt
+    demos/MMk_shutdown.rb
+    demos/CancelQ.rb
+    demos/sptf.rb
   ]
-  s.required_ruby_version = '>= 1.8.1'
+  s.required_ruby_version = '>= 2.3.0'
   s.license = 'MIT'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simplekit
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 1.0.0
 platform: ruby
 authors:
 - Paul J Sanchez
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-12-01 00:00:00.000000000 Z
+date: 2018-07-12 00:00:00.000000000 Z
 dependencies: []
 description: This is a minimal discrete event simulation scheduling algorithm for
   educational use.
@@ -17,6 +17,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- demos/CancelQ.rb
+- demos/MMk.rb
+- demos/MMk_reference_output.txt
+- demos/MMk_shutdown.rb
+- demos/sptf.rb
 - lib/priority_queue.rb
 - lib/simplekit.rb
 - simplekit.gemspec
@@ -32,7 +37,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 1.8.1
+      version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -40,7 +45,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.14
+rubygems_version: 2.7.7
 signing_key: 
 specification_version: 4
 summary: Discrete event simulation engine.