em-throttled_queue 1.0.2

data/.yardopts

@@ -0,0 +1,2 @@
+--title "EM-Throttled Queue"
+--markup markdown

data/Gemfile

@@ -0,0 +1,10 @@
+source :rubygems
+
+gem 'eventmachine'
+
+group :development do
+  gem 'jeweler', '~> 1.5'
+  gem 'rake'
+  gem 'yard'
+  gem 'rdiscount'
+end

data/Gemfile.lock

@@ -0,0 +1,22 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    eventmachine (0.12.10)
+    git (1.2.5)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.8.7)
+    rdiscount (1.6.8)
+    yard (0.6.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  eventmachine
+  jeweler (~> 1.5)
+  rake
+  rdiscount
+  yard

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2011 Kim Burgestrand
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,42 @@
+# EM-Throttled_Queue is a throttled queue (surprise, surprise!)
+[ThrottledQueue](http://rdoc.info/github/Burgestrand/em-throttled_queue/master/EventMachine/ThrottledQueue) is just like an [EM::Queue](http://rdoc.info/github/eventmachine/eventmachine/master/EventMachine/Queue), but will pop items off itself at a pace specified by you!
+
+Version v1.0.0 and v1.0.1 has an unintentional flaw (result of coding while tired) and should not be used. v1.0.2 is coming as soon as issue #2 is resolved. They have been yanked from rubygems.
+
+Example
+-------
+
+    # Example code that will pop off 2 items in total within a period of
+    # one second. The other items are not popped because of throttle.
+    EM::run do
+      # Create a queue that will pop off maximum of 2 items per second,
+      # with a refill-limit of 1 second.
+      queue = EM::ThrottledQueue.new(2)
+  
+      queue.push 1 # you can push one item at a time
+      queue.push 2, 3, 4, 5, 6 # or several at once
+  
+      5.times { queue.pop(&EM::Callback(Object, :puts)) }
+  
+      EM::add_timer(1) { EM::stop }
+    end
+   
+    # Output:
+    # 1
+    # 2
+
+What problem does EM-Throttled_Queue solve?
+-------------------------------------------
+At [radiofy](http://radiofy.se/) we consume a lot of external services. As we are rebuilding our internal structures we will be using EventMachine for the consumption of said services. Some of them have an applied rate-limit that will punish you if you don’t restrain how many queries you execute.
+
+As a result, we need to call our blocks of code within the allowed rate-limit. For example, the [Spotify Metadata API](http://developer.spotify.com/en/metadata-api/overview/) allow a maximum of 10 requests per second, and if exceeded will force you to wait 10 seconds (essentially losing 90 reqs/10 seconds). EM::ThrottledQueue will allow us to easily limit how many calls we make per second to their API.
+
+How do I contribute?
+--------------------
+Fork, add tests (important!), add your code and send a pull request. If you wish to report an issue, please use the GitHub issue tracker. I can also be contacted by mail (visible on [my GitHub user page](http://github.com/Burgestrand)).
+
+As far as development dependencies goes they are all specified in the Gemfile. Once you have checked out the code, a mere `bundle install` should fetch them all for you! \o/
+
+Why don’t you support 1.8.7?
+----------------------------
+There currently is no reason for me to do so. If you believe there is, file an issue.

data/Rakefile

@@ -0,0 +1,30 @@
+require 'bundler/setup'
+
+require 'jeweler'
+require './lib/em/throttled_queue/version'
+Jeweler::Tasks.new do |gem|
+  gem.name     = "em-throttled_queue"
+  gem.homepage = "http://github.com/Burgestrand/em-throttled_queue"
+  
+  gem.license  = "X11 License"
+  
+  gem.summary = "A rate-limited Queue for EventMachine"
+  gem.authors = ["Kim Burgestrand"]
+  gem.email   = "kim@burgestrand.se"
+  
+  gem.version = EventMachine::ThrottledQueue::VERSION
+  gem.required_ruby_version = '~> 1.9'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'yard'
+require 'yard/rake/yardoc_task'
+YARD::Rake::YardocTask.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:spec) do |t|
+  t.pattern = 'spec/*.rb'
+end
+
+task :release => ['gemspec:release', 'git:release', 'gemcutter:release']
+task :default => :spec

data/em-throttled_queue.gemspec

@@ -0,0 +1,65 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{em-throttled_queue}
+  s.version = "1.0.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Kim Burgestrand"]
+  s.date = %q{2011-02-13}
+  s.email = %q{kim@burgestrand.se}
+  s.extra_rdoc_files = [
+    "LICENSE",
+    "README.markdown"
+  ]
+  s.files = [
+    ".yardopts",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE",
+    "README.markdown",
+    "Rakefile",
+    "em-throttled_queue.gemspec",
+    "lib/em/throttled_queue.rb",
+    "lib/em/throttled_queue/version.rb",
+    "lib/eventmachine/throttled_queue.rb",
+    "spec/throttled_queue.rb"
+  ]
+  s.homepage = %q{http://github.com/Burgestrand/em-throttled_queue}
+  s.licenses = ["X11 License"]
+  s.require_paths = ["lib"]
+  s.required_ruby_version = Gem::Requirement.new("~> 1.9")
+  s.rubygems_version = %q{1.5.0}
+  s.summary = %q{A rate-limited Queue for EventMachine}
+  s.test_files = [
+    "spec/throttled_queue.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<eventmachine>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5"])
+      s.add_development_dependency(%q<rake>, [">= 0"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
+      s.add_development_dependency(%q<rdiscount>, [">= 0"])
+    else
+      s.add_dependency(%q<eventmachine>, [">= 0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5"])
+      s.add_dependency(%q<rake>, [">= 0"])
+      s.add_dependency(%q<yard>, [">= 0"])
+      s.add_dependency(%q<rdiscount>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<eventmachine>, [">= 0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5"])
+    s.add_dependency(%q<rake>, [">= 0"])
+    s.add_dependency(%q<yard>, [">= 0"])
+    s.add_dependency(%q<rdiscount>, [">= 0"])
+  end
+end
+

data/lib/em/throttled_queue.rb

@@ -0,0 +1,76 @@
+# coding: utf-8
+require 'eventmachine'
+require 'em/throttled_queue/version'
+
+# @see https://github.com/eventmachine/eventmachine
+module EventMachine
+  # An EM::Queue with a rate-limit applied to it. This is useful if you
+  # wish to consume items at a limited pace.
+  # 
+  # @todo Add a maximum size-limit on amount of items in queue.
+  class ThrottledQueue < Queue
+    # Create a new rate-limited queue.
+    # 
+    # @example
+    # 
+    #   EM::ThrottledQueue.new(10)
+    #   # => allows maximum 10 deqs every second
+    # 
+    # @param [Fixnum] maximum of dequeues every second
+    def initialize(limit)
+      @credits = @limit = limit.to_i
+      @ticker  = EM::add_periodic_timer(1) do
+        @credits = @limit
+        scheduled_dequeue
+      end
+      
+      super()
+    end
+    
+    # Pop an item off the queue as soon as conditions allow, passing it
+    # to the given block.
+    #
+    # @note The given block is executed within the reactor thread.
+    # @yield [item] callback to execute when item is popped off
+    # @yieldparam item an item from the queue
+    # @return (see #interact)
+    # @see http://rdoc.info/github/eventmachine/eventmachine/master/EventMachine.Callback
+    def pop(&block)
+      interact { @popq.push(block) }
+    end
+    
+    # Push items onto the queue (from within the reactor thread) asap.
+    # 
+    # @note This call is thread-safe.
+    # @param [item, …] items items to be pushed onto the queue
+    # @return (see #interact)
+    def push(*items)
+      interact { @items.push(*items) }
+    end
+    
+    private
+      # Helper method to schedule queue interaction and then _dequeue.
+      # 
+      # @yield block to call within EM::schedule
+      # @return [ThrottledQueue]
+      def interact(&block)
+        EM::schedule do
+          block.call
+          # next_tick to avoid locking up caller in a dequeuing loop
+          EM::next_tick method(:scheduled_dequeue)
+        end
+        self
+      end
+      
+      # Dequeue as many items as ossible.
+      # 
+      # @return [ThrottledQueue]
+      def scheduled_dequeue
+        until @credits < 1 || @items.empty? || @popq.empty?
+          @credits -= 1
+          @popq.shift.call @items.shift
+        end
+        self
+      end
+  end
+end

data/lib/em/throttled_queue/version.rb

@@ -0,0 +1,7 @@
+module EventMachine
+  class ThrottledQueue < Queue
+    # Gem version, following Semantic Versioning since v1.0.2
+    # @see http://semver.org/
+    VERSION = [1, 0, 2].join('.')
+  end
+end

data/lib/eventmachine/throttled_queue.rb

@@ -0,0 +1 @@
+require 'em/throttled_queue'

data/spec/throttled_queue.rb

@@ -0,0 +1,75 @@
+require 'em/throttled_queue'
+require 'minitest/autorun'
+require 'minitest/spec'
+
+class << MiniTest::Spec
+  def it_enhanced(*args, &block)
+    it_original(*args) do
+      EM::run(&block)
+    end
+  end
+  
+  alias_method :it_original, :it
+  alias_method :it, :it_enhanced
+end
+
+describe EM::ThrottledQueue do
+  it "should pop items in FIFO order" do
+    queue = EM::ThrottledQueue.new(1)
+    pushed_items = [1, 2, 3, 4]
+    popped_items = []
+    queue.push(*pushed_items)
+    
+    1.upto(4) do |i|
+      queue.pop do |j|
+        popped_items << j
+        
+        if i == 4
+          popped_items.must_equal pushed_items
+          EM::stop
+        end
+      end
+    end
+  end
+  
+  it "should pop items within the rate limit" do
+    ticks = 0
+    deqs  = 0
+    
+    queue = EM::ThrottledQueue.new(10) # 10 deqs/s
+    queue.push(*(1..1000).to_a)
+    queue.size.must_equal 1000
+    
+    EM::add_timer(0.5) do
+      deqs.must_equal 10
+      (ticks > 100).must_equal true # need good margin
+      EM::stop
+    end
+    
+    ticker = proc do |me|
+      ticks += 1
+      queue.pop { deqs += 1 }
+      EM::next_tick { me.call(me) }
+    end
+    
+    ticker.call(ticker)
+  end
+  
+  it "should not build up credits over time" do
+    deqs = 0
+    
+    queue = EM::ThrottledQueue.new(10) # 10 deqs/s
+    queue.push(*(1..1000).to_a)
+    
+    EM::add_timer(3) do
+      # Oh this is bad… test tied to implementation details!
+      queue.instance_variable_get("@credits").must_equal 10
+      EM::stop
+    end
+  end
+  
+  it "should load the version" do
+    defined?(EM::ThrottledQueue::VERSION).wont_be_nil
+    EM::stop
+  end
+end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification 
+name: em-throttled_queue
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 1.0.2
+platform: ruby
+authors: 
+- Kim Burgestrand
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-02-13 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: eventmachine
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "1.5"
+  type: :development
+  prerelease: false
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rake
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: yard
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rdiscount
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id005
+description: 
+email: kim@burgestrand.se
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.markdown
+files: 
+- .yardopts
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.markdown
+- Rakefile
+- em-throttled_queue.gemspec
+- lib/em/throttled_queue.rb
+- lib/em/throttled_queue/version.rb
+- lib/eventmachine/throttled_queue.rb
+- spec/throttled_queue.rb
+has_rdoc: true
+homepage: http://github.com/Burgestrand/em-throttled_queue
+licenses: 
+- X11 License
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ~>
+    - !ruby/object:Gem::Version 
+      version: "1.9"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.0
+signing_key: 
+specification_version: 3
+summary: A rate-limited Queue for EventMachine
+test_files: 
+- spec/throttled_queue.rb