sendq 0.0.1

data/lib/sendq.rb

@@ -0,0 +1,124 @@
+require 'time'
+
+#
+# SendQ - Easy access to time-constrained send queues.
+#
+# Example:
+#
+#  output = [] 
+#  # process a maximum of 5 within 3 seconds
+#  s = SendQ.new(5, 3) { |x| output.push(x) }
+#  (0..9).each { |x| s.add(x) }
+#  s.run
+#  output # => [0,1,2,3,4]
+#  s.queue # => [5,6,7,8,9]
+#  s.run # nothing changes, we're still waiting to run
+#  sleep 3 # wait for the constraint to expire
+#  s.run
+#  output # => [0,1,2,3,4,5,6,7,8,9] 
+#  s.queue # => []
+#
+# Note: The calculation is very simple and can probably be gamed. It simply
+# tests if the last run, subtracted from the current time, is greater than the
+# interval.
+#
+# The clock is by default the unix epoch and therefore is restricted to a
+# minimum granularity of 1 second. If you wish to change this or otherwise
+# manipulate the constraint, see SendQ.clock.
+#
+# Simple accessors (all can be modified):
+# * queue: this is the internal queue that will be exhausted on runs. See SendQ#add.
+# * filled: this is the number filled in the current interval. guaranteed to never be greater than max_per_interval
+# * action: this is the block you supplied to the constructor.
+# * max_per_interval: the maximum number of queue elements to exhaust in the timeframe of the interval.
+#
+#--
+#
+# Please see the COPYING file in the source distribution for copyright information.
+#
+#++ 
+
+class SendQ
+
+    VERSION = "0.0.1"
+
+    attr_accessor :queue
+    attr_accessor :filled
+    attr_accessor :action
+    attr_accessor :max_per_interval
+
+    #
+    # Constructor.
+    #
+    # * max_per_interval (required): the maximum amount of queue elements to process in a given interval.
+    # * interval (optional, default 1 second): if this much time has passed, reset how many can be filled in the next run to max_per_interval. See SendQ.clock for more information on how to manipulate the clock.
+    # * action (required): A block that describes what you want to do with each element in the queue. This block must take one argument - the element of the queue to process.
+    #
+    def initialize(max_per_interval, interval = 1, &action)
+        raise ArgumentError, "Requires an action block to construct" unless action
+
+        @interval = interval
+        @last_run = 0
+        @max_per_interval = max_per_interval
+        @queue    = []
+        @filled   = 0
+        @action   = action
+    end
+
+    #
+    # Add an item to the queue.
+    #
+    # Like any normal queue, items are processed in FIFO order.
+    #
+    def add(item)
+        @queue.push(item)
+    end
+
+    #
+    # Evaluate how many items to process in the queue and then process them.
+    # Update the clock with its current value.
+    #
+    def run
+        fill     = [how_many, @queue.size].min
+        @filled += fill
+        fill.times do @action.call(@queue.shift) end
+        @last_run = clock
+    end
+
+    protected
+
+    #
+    # Get this SendQs clock.
+    # 
+    # This defaults to Time.now.to_i. You can of course redefine it. Example:
+    #
+    #  sendq = SendQ.new { ...} 
+    #  def sendq.clock Time.now.to_f
+    #
+    # For fractional seconds.
+    #
+    # Note:: All of the internal clock management is done via simple
+    # mathematical operators and comparison operators. Therefore, your clock can
+    # realistically be anything that implemements these operators.
+    #
+    def clock
+        Time.now.to_i
+    end
+
+    #
+    # Return how many items in the queue to process this run.
+    #
+    # Side Effect: will reset the filled count if we have determined the
+    # interval for the existing filled count has expired.
+    #
+    def how_many
+        if (clock - @last_run) >= @interval then
+        	  @filled = 0
+        	  @max_per_interval
+        elsif @filled < @max_per_interval
+            @max_per_interval - @filled
+        else
+            0
+        end
+    end
+end

data/test/test_sendq.rb

@@ -0,0 +1,74 @@
+#
+# Please see the COPYING file in the source distribution for copyright information.
+# 
+require 'test/unit'
+require 'sendq'
+
+class TestSendQ < Test::Unit::TestCase
+    def setup
+        @output = []
+    end
+
+    def test_construct
+        assert_raise(ArgumentError) { SendQ.new }
+        assert_raise(ArgumentError) { SendQ.new(10) }
+        assert_raise(ArgumentError) { SendQ.new(10, 1, 12) }
+        assert_nothing_raised { SendQ.new(10) { puts "Foo" } }
+    end
+
+    def test_fill_queue
+        s = SendQ.new(1) { }
+        (0..10).each { |x| s.add(x) }
+        assert_equal(s.queue, (0..10).to_a)
+    end
+
+    def test_run_basic
+        s = SendQ.new(5) { |x| @output.push(x) }
+        (0..10).each { |x| s.add(x) }
+        s.run
+        assert_equal(@output, (0..4).to_a)
+        assert_equal(s.queue, (5..10).to_a)
+    end
+
+    def test_run_multiple
+        # XXX obviously, this test will have some failures if it takes more
+        #     than 3 seconds to get to the sleep statement
+        s = SendQ.new(5, 3) { |x| @output.push(x) }
+        (0..10).each { |x| s.add(x) }
+        s.run
+        assert_equal(@output, (0..4).to_a)
+        assert_equal(s.queue, (5..10).to_a)
+
+        assert_equal(s.max_per_interval, s.filled)
+
+        s.run
+
+        # should be exactly the same
+        assert_equal(@output, (0..4).to_a)
+        assert_equal(s.queue, (5..10).to_a)
+
+        sleep 3
+
+        s.run
+
+        assert_equal(@output, (0..9).to_a)
+        assert_equal(s.queue, [10])
+
+        sleep 3
+
+        s.run
+
+        assert_equal(@output, (0..10).to_a)
+        assert_equal(s.queue, [])
+
+        assert_equal(s.filled, 1)
+
+        (11..14).each { |x| s.add(x) }
+
+        s.run
+
+        assert_equal(@output, (0..14).to_a)
+        assert_equal(s.queue, [])
+        assert_equal(s.max_per_interval, s.filled)
+    end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification 
+name: sendq
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Erik Hollensbe
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-07-04 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: 
+email: erik@hollensbe.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/sendq.rb
+- test/test_sendq.rb
+has_rdoc: true
+homepage: 
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: sendq
+rubygems_version: 1.1.1
+signing_key: 
+specification_version: 2
+summary: A library for queues that can only release so much information over a given timespan
+test_files: []
+