throttler 0.2.4 → 0.3.0

data/.gitignore

@@ -0,0 +1,2 @@
+.bundle
+pkg

data/.travis.yml

@@ -0,0 +1,3 @@
+rvm:
+  - 1.8.7
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,2 @@
+source 'http://rubygems.org'
+gemspec

data/Gemfile.lock

@@ -0,0 +1,16 @@
+PATH
+  remote: .
+  specs:
+    throttler (0.3.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    rake (0.9.2.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake (~> 0.9.2)
+  throttler!

data/LICENSE

@@ -1,7 +1,7 @@
 (The MIT License)
- 
-Copyright (c) 2010 Paper Cavalier
- 
+
+Copyright (c) 2012 Hakan Ensari
+
 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
@@ -9,10 +9,10 @@ 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.

data/README.md

@@ -1,26 +1,40 @@
 Throttler
 =========
 
-Throttler is a tired, cranky module that helps you throttle stuff in parallel-running Ruby scripts on a single machine.
+[![travis] [1]] [2]
 
-![Mapplethorpe](https://github.com/papercavalier/throttler/raw/master/mapplethorpe_chains.jpg)
+Throttler rate-limits code execution across threads or processes on a server.
 
-Example
--------
+![Mapplethorpe][3]
 
-Our very own use case: We have multiple Resque workers hitting the Amazon IP on multiple addresses and want to make sure they don't fire more than once per locale per IP.
+Installation
+------------
 
-Here's some pseudo code:
+```ruby
+# in your Gemfile
+gem 'throttler'
+```
 
-    class Worker
-      include Throttler
+Throttler works only on platforms that support file locking.
 
-      def perform(*args)
-        scope = "#{locale}-#{interface}"
-        freq  = 1.0
+Usage
+-----
 
-        throttle(scope, freq) do
-          # perform a request
-        end
-      end
+The following background job ensures workers will not scrape a site faster than
+once every second per IP address.
+
+```ruby
+class Scrape
+  def self.perform(site, ip_address, *ids)
+    # The block is syntactic sugar.
+    Throttler.limit 1.0, site, ip_address do
+      spider = Spider.new site, ip_address
+      spider.scrape *ids
     end
+  end
+end
+```
+
+[1]: https://secure.travis-ci.org/hakanensari/throttler.png
+[2]: http://travis-ci.org/hakanensari/throttler
+[3]: http://f.cl.ly/items/2S343U141D0N3b3h1K09/Mapplethorpe.png

data/Rakefile

@@ -0,0 +1,9 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |test|
+  test.libs += %w{lib test}
+  test.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/lib/throttler/throttle.rb

@@ -0,0 +1,48 @@
+module Throttler
+  class Throttle
+    class << self
+      attr_accessor :tmp_dir
+    end
+
+    @tmp_dir = '/tmp'
+
+    def initialize(namespace)
+      @namespace = namespace
+      @file = File.open(path, File::RDWR|File::CREAT)
+    end
+
+    def lock
+      @file.flock(File::LOCK_EX)
+    end
+
+    def path
+      "#{self.class.tmp_dir}/.lock-#{@namespace}"
+    end
+
+    def hold(wait)
+      sleep [timestamp + wait - now, 0.0].max
+      timestamp!
+    end
+
+    def unlock
+      @file.flock(File::LOCK_UN)
+      @file.close
+    end
+
+    private
+
+    def now
+      Time.now.to_f
+    end
+
+    def timestamp
+      @file.rewind
+      @file.gets.to_f
+    end
+
+    def timestamp!
+      @file.rewind
+      @file.write now
+    end
+  end
+end

data/lib/throttler/version.rb

@@ -1,4 +1,4 @@
-module Throttler #:nodoc:
-  VERSION = "0.2.4"
+module Throttler
+  VERSION = '0.3.0'
 end
 

data/lib/throttler.rb

@@ -1,16 +1,23 @@
-require "throttler/timer"
+require 'throttler/throttle'
 
-# = Throttler
-#
-# A tired, cranky module that helps you throttle stuff in parallel-running Ruby
-# scripts on a single machine. It gets the job done.
+# Throttler rate-limits code execution.
 module Throttler
-  def throttle(scope="throttler",freq=1.0)
-    timer = Timer.new(scope)
-    timer.lock
-    sleep [timer.timestamp + freq - Time.now.to_f, 0.0].max
-    timer.timestamp = Time.now.to_f
-    timer.unlock
+  # Ensures subsequent code, including any given block, is executed at most per
+  # every `wait` seconds.
+  #
+  # Optionally takes a splat of words to namespace the throttle.
+  def self.limit(wait, *words)
+    words << 'default' if words.empty?
+    namespace = words.join '-'
+
+    begin
+      throttle = Throttle.new namespace
+      throttle.lock
+      throttle.hold wait
+    ensure
+      throttle.unlock
+    end
+
     yield if block_given?
   end
 end

data/test/throttler_test.rb

@@ -0,0 +1,20 @@
+require 'test/unit'
+require 'benchmark'
+require 'throttler'
+
+class Work
+  def self.perform
+    Throttler.limit 0.1
+  end
+end
+
+class ThrottlerTest < Test::Unit::TestCase
+  def test_throttling
+    time = Benchmark.realtime do
+      11.times { Process.fork { Work.perform } }
+      Process.waitall
+    end
+
+    assert_equal 1, time.to_i
+  end
+end

data/throttler.gemspec

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path('../lib', __FILE__)
+require 'throttler/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'throttler'
+  s.version     = Throttler::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Hakan Ensari', 'Piotr Łaszewski']
+  s.email       = ['hakan.ensari@papercavalier.com']
+  s.homepage    = 'https://github.com/hakanensari/throttler'
+  s.summary     = 'Rate-limits code execution'
+  s.description = 'Throttler rate-limits code execution across threads or processes.'
+
+  s.add_development_dependency 'rake', '~> 0.9.2'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ['lib']
+end
+

metadata

@@ -1,101 +1,70 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: throttler
-version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 0
-  - 2
-  - 4
-  version: 0.2.4
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Hakan Ensari
-- "Piotr \xC5\x81aszewski"
+- Piotr Łaszewski
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2010-11-29 00:00:00 +00:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
-  name: rspec
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+date: 2012-03-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70196529042720 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 2
-        - 1
-        - 0
-        version: 2.1.0
+      - !ruby/object:Gem::Version
+        version: 0.9.2
   type: :development
-  version_requirements: *id001
-description: A tired, cranky module that helps you throttle stuff in parallel-running Ruby scripts on a single machine.
-email: 
-- code@papercavalier.com
+  prerelease: false
+  version_requirements: *70196529042720
+description: Throttler rate-limits code execution across threads or processes.
+email:
+- hakan.ensari@papercavalier.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
-- lib/throttler/timer.rb
-- lib/throttler/version.rb
-- lib/throttler.rb
+files:
+- .gitignore
+- .travis.yml
+- Gemfile
+- Gemfile.lock
 - LICENSE
 - README.md
-- spec/fixtures/foo.rb
-- spec/integration/blocks_with_long_execution_time_spec.rb
-- spec/integration/fibers_spec.rb
-- spec/integration/loop_spec.rb
-- spec/integration/processes_spec.rb
-- spec/integration/threads_spec.rb
-- spec/spec_helper.rb
-- spec/unit/throttler/timer_spec.rb
-- spec/unit/throttler_spec.rb
-has_rdoc: true
-homepage: http://github.com/papercavalier/throttler
+- Rakefile
+- lib/throttler.rb
+- lib/throttler/throttle.rb
+- lib/throttler/version.rb
+- test/throttler_test.rb
+- throttler.gemspec
+homepage: https://github.com/hakanensari/throttler
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
-rubyforge_project: throttler
-rubygems_version: 1.3.7
+rubyforge_project: 
+rubygems_version: 1.8.11
 signing_key: 
 specification_version: 3
-summary: A tired, cranky throttler
-test_files: 
-- spec/fixtures/foo.rb
-- spec/integration/blocks_with_long_execution_time_spec.rb
-- spec/integration/fibers_spec.rb
-- spec/integration/loop_spec.rb
-- spec/integration/processes_spec.rb
-- spec/integration/threads_spec.rb
-- spec/spec_helper.rb
-- spec/unit/throttler/timer_spec.rb
-- spec/unit/throttler_spec.rb
+summary: Rate-limits code execution
+test_files:
+- test/throttler_test.rb

data/lib/throttler/timer.rb

@@ -1,27 +0,0 @@
-module Throttler #:nodoc:
-  class Timer
-    def initialize(scope)
-      path = "/tmp/.#{scope}"
-      @timer = File.open(path, File::RDWR|File::CREAT)
-    end
-
-    def lock
-      @timer.flock(File::LOCK_EX)
-    end
-
-    def timestamp
-      @timestamp ||= @timer.gets.to_f
-    end
-
-    def timestamp=(time)
-      @timer.rewind
-      @timer.write(time)
-      @timestamp = time
-    end
-
-    def unlock
-      @timer.flock(File::LOCK_UN)
-      @timer.close
-    end
-  end
-end

data/spec/fixtures/foo.rb

@@ -1,18 +0,0 @@
-$:.push File.expand_path("../../../lib", __FILE__)
-require "throttler"
-
-class Foo
-  include Throttler
-
-  def bar
-    throttle("foo", 2.0) { }
-  end
-
-  def control; end
-end
-
-if ARGV.size == 0
-  Foo.new.bar
-else
-  Foo.new.control
-end

data/spec/integration/blocks_with_long_execution_time_spec.rb

@@ -1,33 +0,0 @@
-require "fileutils"
-require "spec_helper"
-
-describe "Throttler" do
-  before do
-    class Foo
-      include Throttler
-
-      def bar
-        throttle("foo") do
-          yield # so we can count
-          sleep 10
-        end
-      end
-    end
-
-    FileUtils.rm "/tmp/.foo", :force => true
-  end
-
-  it "throttles threads with long execution times" do
-    count = 0
-
-    threads = 10.times.collect do
-      Thread.new do
-        loop{ Foo.new.bar{ count += 1 } }
-      end
-    end
-    sleep 3.25
-    threads.each { |t| Thread.kill(t) }
-
-    count.should eql 4
-  end
-end

data/spec/integration/fibers_spec.rb

@@ -1,29 +0,0 @@
-require "benchmark"
-require "fiber"
-require "fileutils"
-require "spec_helper"
-
-describe "Throttler" do
-  before do
-    class Foo
-      include Throttler
-
-      def bar
-        throttle { }
-      end
-    end
-
-    FileUtils.rm "/tmp/.throttler", :force => true
-  end
-
-  it "throttles fibers" do
-    time = Benchmark.realtime do
-      fib = Fiber.new do
-        loop{ Foo.new.bar; Fiber.yield }
-      end
-      3.times { fib.resume }
-    end
-
-    time.should be_within(0.1).of(2)
-  end
-end

data/spec/integration/loop_spec.rb

@@ -1,27 +0,0 @@
-require "benchmark"
-require "fileutils"
-require "spec_helper"
-
-describe "Throttler" do
-  before do
-    class Foo
-      include Throttler
-
-      def bar
-        throttle { }
-      end
-    end
-
-    FileUtils.rm "/tmp/.throttler", :force => true
-  end
-
-  it "throttles a loop" do
-    time = Benchmark.realtime do
-      3.times do
-        Foo.new.bar
-      end
-    end
-
-    time.should be_within(0.1).of(2)
-  end
-end

data/spec/integration/processes_spec.rb

@@ -1,22 +0,0 @@
-require "benchmark"
-require "fileutils"
-require "spec_helper"
-
-
-describe "Throttler" do
-  before do
-    FileUtils.rm "/tmp/.foo", :force => true
-  end
-
-  it "throttles concurrent processes" do
-    startup_time = Benchmark.realtime do
-      `ruby #{File.dirname(__FILE__) + "/../fixtures/foo.rb"} control`
-    end
-
-    time = Benchmark.realtime do
-      4.times{ `ruby #{File.dirname(__FILE__) + "/../fixtures/foo.rb"}` }
-    end
-
-    (time - startup_time).should be_within(0.5).of(6.0)
-  end
-end

data/spec/integration/threads_spec.rb

@@ -1,51 +0,0 @@
-require "fileutils"
-require "spec_helper"
-
-describe "Throttler" do
-  before do
-    class Foo
-      include Throttler
-
-      def bar
-        throttle { }
-      end
-
-      def baz
-        throttle("foo-prime"){ }
-      end
-    end
-
-    %w{throttler foo-prime}.each do |file|
-      FileUtils.rm "/tmp/.#{file}", :force => true
-    end
-  end
-
-  it "throttles threads" do
-    count = 0
-    threads = 10.times.collect do
-      Thread.new do
-        loop { Foo.new.bar; count += 1 }
-      end
-    end
-    sleep 3.25
-    threads.each { |t| Thread.kill(t) }
-
-    count.should eql 4
-  end
-
-  it "throttles by scope" do
-    count = 0
-    threads = 10.times.collect do
-      Thread.new do
-        loop do
-          Foo.new.send(count % 2 == 0 ? :bar : :baz)
-          count += 1
-        end
-      end
-    end
-    sleep 3.25
-    threads.each { |t| Thread.kill(t) }
-
-    count.should eql 8
-  end
-end

data/spec/spec_helper.rb

@@ -1,2 +0,0 @@
-require "rspec"
-require File.expand_path("../../lib/throttler", __FILE__)

data/spec/unit/throttler/timer_spec.rb

@@ -1,65 +0,0 @@
-require "spec_helper"
-require "benchmark"
-require "fileutils"
-
-module Throttler
-  describe Timer do
-    before do
-      FileUtils.rm "/tmp/.foo", :force => true
-    end
-
-    let!(:timer) do
-      Timer.new("foo")
-    end
-
-    it "creates a file" do
-      File.exists?("/tmp/.foo").should be_true
-    end
-
-    context "#lock" do
-      it "locks the file" do
-        timer.lock
-        File.open("/tmp/.foo") do |f|
-          f.flock(File::LOCK_EX | File::LOCK_NB).should be_false
-        end
-      end
-    end
-
-    context "#timestamp" do
-      it "gets the timestamp" do
-        now = Time.now.to_f
-        File.open("/tmp/.foo", "w") { |f| f.write(now) }
-        timer.timestamp.should be_within(0.1).of(now)
-      end
-
-      it "returns 0.0 when file is first created" do
-        timer.timestamp.should eql(0.0)
-      end
-    end
-
-    context "#timestamp=" do
-      it "sets the timestamp" do
-        now = Time.now.to_f
-        timer.timestamp= now
-
-        # We need to close the file first
-        timer.instance_variable_get(:@timer).close
-
-        File.open("/tmp/.foo") do |f|
-          f.gets.to_f.should be_within(0.1).of(now)
-        end
-      end
-    end
-
-    context "#unlock" do
-      it "unlocks the file" do
-        timer.lock
-        timer.unlock
-
-        File.open("/tmp/.foo") do |f|
-          f.flock(File::LOCK_EX | File::LOCK_NB).should_not be_false
-        end
-      end
-    end
-  end
-end

data/spec/unit/throttler_spec.rb

@@ -1,44 +0,0 @@
-require "benchmark"
-require "fileutils"
-require "spec_helper"
-
-describe Throttler do
-  before do
-    class Foo
-      include Throttler
-    end
-
-    FileUtils.rm "/tmp/.throttler", :force => true
-  end
-
-  let!(:foo) do
-    Foo.new
-  end
-
-  describe "#throttle" do
-    it "removes a lock when an exception is raised" do
-      expect do
-        foo.throttle { raise }
-      end.to raise_error
-
-      File.open("/tmp/.throttler") do |f|
-        f.flock(File::LOCK_EX | File::LOCK_NB).should_not be_false
-      end
-    end
-
-    context "by default" do
-      it "names scope as `throttler`" do
-        foo.throttle
-        FileTest.exists?("/tmp/.throttler").should be_true
-      end
-
-      it "throttles for one second" do
-        time = Benchmark.realtime do
-          2.times{ foo.throttle }
-        end
-
-        time.should be_within(0.1).of(1)
-      end
-    end
-  end
-end