discrete_event 1.0.0 → 1.1.0

data/README.rdoc

@@ -2,6 +2,8 @@
 
 http://github.com/jdleesmiller/discrete_event
 
+{<img src="https://secure.travis-ci.org/jdleesmiller/discrete_event.png"/>}[http://travis-ci.org/jdleesmiller/discrete_event]
+
 == SYNOPSIS
 
 This gem provides some tools for discrete event simulation (DES) in ruby. The
@@ -130,6 +132,11 @@ You may also be interested in the Ruby bindings of the GNU Science Library, whic
 
 == HISTORY
 
+<em>1.1.0:</em>
+* compatibility with PQueue 2.x; fix for event cancellation (thanks: joshcarter)
+* added {DiscreteEvent::EventQueue#run_to}
+* updated dependency versions
+
 <em>1.0.0:</em>
 * split {DiscreteEvent::EventQueue} out of DiscreteEvent::Simulation for
   easier sharing between objects

data/lib/discrete_event/event_queue.rb

@@ -13,7 +13,7 @@ module DiscreteEvent
   #
   class EventQueue
     #
-    # Event queue entry for events; you do not need to use this class directly.
+    # Event queue entry for events.
     #
     Event = Struct.new(:time, :action)
 
@@ -21,7 +21,7 @@ module DiscreteEvent
     # Current time (taken from the currently executing event, if any). You can
     # use floating point or integer time.
     #
-    # @return [Number]
+    # @return [Numeric]
     #
     attr_reader :now
 
@@ -42,32 +42,54 @@ module DiscreteEvent
     # Schedule +action+ (a block) to run at the given +time+; +time+ must not be
     # in the past.
     #
-    # @param [Number] time at which +action+ should run; must be >= {#now}
+    # @param [Numeric] time at which +action+ should run; must be >= {#now}
     #
     # @yield [] action to be run at +time+
     #
-    # @return [nil]
+    # @return [Event]
     #
     def at time, &action
       raise "cannot schedule event in the past" if time < now
-      @events.push(Event.new(time, action))
-      nil
+      event = Event.new(time, action)
+      @events.push(event)
+      event
     end
 
     #
     # Schedule +action+ (a block) to run after the given +delay+ (with respect
     # to {#now}).
     #
-    # @param [Number] delay after which +action+ should run; non-negative
+    # @param [Numeric] delay after which +action+ should run; non-negative
     #
     # @yield [] action to be run after +delay+
     #
-    # @return [nil]
+    # @return [Event]
     #
     def after delay, &action
       at(@now + delay, &action)
     end
 
+    #
+    # Cancel an event previously created with {#at} or {#after}.
+    #
+    # @param [Event] event the event to cancel
+    #
+    # @return [nil]
+    #
+    def cancel event
+      # not very efficient but hopefully not used very often
+      temp = []
+      until @events.empty? || @events.top.time > event.time
+        e = @events.pop
+        break if e.equal?(event)
+        temp << e
+      end
+      temp.each do |e|
+        @events.push(e)
+      end
+      nil
+    end
+
     #
     # Schedule +action+ (a block) to run for each element in the given list
     # (possibly at different times).
@@ -152,7 +174,7 @@ module DiscreteEvent
     # but it is somewhat more efficient to call +recur_after+, and, if you do,
     # the named method is not necessary.
     #
-    # @param [Number] interval non-negative
+    # @param [Numeric] interval non-negative
     #
     # @return [nil]
     #
@@ -199,7 +221,7 @@ module DiscreteEvent
     # (that is, the current event hasn't finished yet, so it's still in some
     # sense the next event).
     #
-    # @return [Number, nil] 
+    # @return [Numeric, nil] 
     #
     def next_event_time
       event = @events.top
@@ -216,25 +238,17 @@ module DiscreteEvent
     # @return [Boolean] false if there are no more events.
     #
     def run_next
-      event = @events.top
+      event = @events.pop
       if event
         # run the action
         @now = event.time
         event.action.call
 
-        # recurring events get special treatment: can avoid doing a push and a
-        # pop by reusing the Event at the top of the heap, but with a new time
-        #
-        # NB: this assumes that the top element in the heap can't change due to
-        # the event that we just ran, which is the case here, because we don't
-        # allow events to be created in the past, and because of the internals
-        # of the PQueue datastructure
+        # Handle recurring events.
         if @recur_interval
           event.time = @now + @recur_interval
-          @events.replace_top(event)
+          @events.push(event)
           @recur_interval = nil
-        else
-          @events.pop
         end
 
         true
@@ -243,11 +257,31 @@ module DiscreteEvent
       end
     end
 
+    #
+    # Run events until the given time (inclusive). When this method returns,
+    # {#now} is +time+, and all events scheduled to run at times up to and
+    # including +time+ have been run.
+    #
+    # @param [Numeric] time to run to (inclusive)
+    #
+    # @return [nil]
+    #
+    def run_to time
+      # add an event to ensure that we actually stop at the given time, even if
+      # there isn't an event in the queue
+      at time do
+        # nothing
+      end
+      run_next until @events.empty? || next_event_time > time
+      nil
+    end
+
     #
     # Allow for the creation of a ruby +Enumerator+ for the simulation. This
-    # yields for each event.
+    # yields for each event. Note that this enumerator may return infinitely
+    # many events, if there are repeating events ({#every}).
     #
-    # @example TODO
+    # @example
     #   eq = EventQueue.new
     #   eq.at 13 do
     #     puts "hi"
@@ -261,7 +295,7 @@ module DiscreteEvent
     #
     # @yield [now] called immediately after each event runs
     #
-    # @yieldparam [Number] now as {#now}
+    # @yieldparam [Numeric] now as {#now}
     #
     # @return [self]
     #

data/lib/discrete_event/events.rb

@@ -14,7 +14,7 @@ module DiscreteEvent
     #
     # @yield [] action to be run at +time+
     #
-    # @return [nil]
+    # @return [Event]
     #
     def at time, &action
       event_queue.at(time, &action)
@@ -27,12 +27,21 @@ module DiscreteEvent
     #
     # @yield [] action to be run after +delay+
     #
-    # @return [nil]
+    # @return [Event]
     #
     def after delay, &action
       event_queue.after(delay, &action)
     end
 
+    #
+    # See {EventQueue#cancel}.
+    #
+    # @return [nil]
+    #
+    def cancel event
+      event_queue.cancel(event)
+    end
+
     #
     # See {EventQueue#at_each}.
     #

data/lib/discrete_event/fake_rand.rb

@@ -16,7 +16,7 @@ module DiscreteEvent
   #   class Foo
   #     def do_stuff
   #       # NB: FakeRand.for won't work if you write "Kernel::rand" instead of
-  #       # just "rand," here.
+  #       # just "rand" here.
   #       puts rand
   #     end
   #   end

data/lib/discrete_event/version.rb

@@ -1,6 +1,6 @@
 module DiscreteEvent
   VERSION_MAJOR = 1
-  VERSION_MINOR = 0
+  VERSION_MINOR = 1
   VERSION_PATCH = 0
   VERSION = [VERSION_MAJOR, VERSION_MINOR, VERSION_PATCH].join('.')
 end

data/test/discrete_event/discrete_event_test.rb

@@ -202,8 +202,7 @@ class TestDiscreteEvent < Test::Unit::TestCase
     assert s.run_next
     assert_nil s.next_event_time
 
-    # as currently implemented, the "next" event includes the current event
-    assert_equal [0, 5], output
+    assert_equal [5, nil], output
   end
 
   def test_enumerator
@@ -253,5 +252,182 @@ class TestDiscreteEvent < Test::Unit::TestCase
       [5, ["a", "b", "c"]],   # third and fourth objects consumed
       [6, ["a", "b", "c", "d"]]], output
   end
+
+  def test_cancel_single
+    #
+    # cancel the only event in the queue
+    #
+    out = []
+    q = EventQueue.new(0)
+    e_a = q.at( 5) { out << :a }
+    q.cancel e_a
+    assert !q.run_next
+    assert_equal [], out
+  end
+
+  def test_cancel_empty
+    #
+    # cancel an event in the past; this should have no effect
+    #
+    out = []
+    q = EventQueue.new(0)
+    e_a = q.at( 5) { out << :a }
+    assert q.run_next
+    assert_equal [:a], out
+    q.cancel e_a
+    assert !q.run_next
+  end
+
+  def test_cancel_first
+    #
+    # should be able to cancel the first (next) event in the queue
+    #
+    out = []
+    q = EventQueue.new(0)
+    e_a = q.at( 5) { out << :a }
+    e_b = q.at(10) { out << :b }
+    q.cancel e_a
+    nil while q.run_next
+    assert_equal [:b], out
+  end
+
+  def test_cancel_first2
+    out = []
+    q = EventQueue.new(0)
+
+    e_a = q.at( 5) do
+      out << :a
+
+      e_c = q.at(6) { out << :c }
+      
+      q.cancel e_a # This should have no effect
+    end
+
+    e_b = q.at(10) do
+      out << :b
+    end
+    
+    nil while q.run_next
+    assert_equal [:a, :c, :b], out
+  end
+
+  def test_cancel_last
+    #
+    # should be able to cancel the last event in the queue
+    #
+    out = []
+    q = EventQueue.new(0)
+    e_a = q.at( 5) { out << :a }
+    e_b = q.at(10) { out << :b }
+    q.cancel e_b
+    nil while q.run_next
+    assert_equal [:a], out
+  end
+
+  def test_cancel_middle
+    #
+    # should be able to cancel an event in the middle of the queue
+    #
+    out = []
+    q = EventQueue.new(0)
+    e_a = q.at( 5) { out << :a }
+    e_b = q.at(10) { out << :b }
+    e_c = q.at(13) { out << :c }
+    q.cancel e_b
+    nil while q.run_next
+    assert_equal [:a, :c], out
+  end
+
+  def test_cancel_at_same_time_1
+    #
+    # if there are two events at the same time, and we cancel one of them, the
+    # correct event should be cancelled (can't just compare on times)
+    #
+    out = []
+    q = EventQueue.new(0)
+    e_a = q.at 10 do
+      out << :a
+    end
+    e_b = q.at 10 do
+      out << :b
+    end
+    assert !e_a.equal?(e_b)
+    q.cancel e_a
+    nil while q.run_next
+    assert_equal [:b], out
+  end
+
+  def test_cancel_at_same_time_2
+    #
+    # see test_cancel_at_same_time_1
+    #
+    out = []
+    q = EventQueue.new(0)
+    e_a = q.at 10 do
+      out << :a
+    end
+    e_b = q.at 10 do
+      out << :b
+    end
+    q.cancel e_b
+    nil while q.run_next
+    assert_equal [:a], out
+  end
+
+  def test_cancel_self
+    #
+    # not sure that there is any reason to do this, but it should work
+    #
+    q = EventQueue.new(0)
+    out = []
+    @e_a = nil
+    @e_a = q.at 3 do
+      out << :a
+      q.cancel @e_a
+    end
+    nil while q.run_next
+    assert_equal [:a], out
+  end
+
+  def test_cancel_from_every_block
+    #
+    # check that we don't change the top event when we cancel
+    #
+    q = EventQueue.new(0)
+    out = []
+    e_a = q.at 10 do # will cancel this one
+      out << :a
+    end
+    q.every 9, 9 do
+      out << q.now
+      q.cancel e_a
+    end
+    q.at 9 do # same time as first instance of repeating event
+      out << :b
+    end
+    3.times { assert q.run_next }
+    assert_equal [9, :b, 18], out
+  end
+
+  def test_run_to
+    q = EventQueue.new(0)
+    out = []
+    q.at 10 do
+      out << :a
+    end
+
+    # run to just before the first event; it should not fire
+    q.run_to 9
+    assert_equal [], out
+    assert_equal 9, q.now
+
+    q.run_to 10
+    assert_equal [:a], out
+    assert_equal 10, q.now
+
+    # running again should have no effect
+    q.run_to 10
+    assert_equal [:a], out
+  end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: discrete_event
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,30 +9,30 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-08 00:00:00.000000000 Z
+date: 2012-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pqueue
-  requirement: &80923720 !ruby/object:Gem::Requirement
+  requirement: &74031670 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: 2.0.2
   type: :runtime
   prerelease: false
-  version_requirements: *80923720
+  version_requirements: *74031670
 - !ruby/object:Gem::Dependency
   name: gemma
-  requirement: &80923460 !ruby/object:Gem::Requirement
+  requirement: &74031240 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 2.4.0
   type: :development
   prerelease: false
-  version_requirements: *80923460
+  version_requirements: *74031240
 description: Some simple primitives for event-based discrete event simulation.
 email:
 - jdleesmiller@gmail.com
@@ -56,7 +56,7 @@ rdoc_options:
 - --main
 - README.rdoc
 - --title
-- discrete_event-1.0.0 Documentation
+- discrete_event-1.1.0 Documentation
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
@@ -67,7 +67,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -360047181
+      hash: 326435089
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -76,7 +76,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -360047181
+      hash: 326435089
 requirements: []
 rubyforge_project: discrete_event
 rubygems_version: 1.8.17