throttled_object 1.0.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+--format=documentation

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in throttled_object.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2012 Filter Squad
+
+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.md

@@ -0,0 +1,40 @@
+# throttled_object
+
+`throttled_object` is a Ruby 1.9 library built on top of ruby to provide throttled access
+to a given object. It provides an interface to interact with an object, sleeping if it's unavailable.
+
+The ideal use for this is for access to APIs with a blocking interface (e.g. Run the code in a thread,
+sleep until it's available).
+
+**PLEASE NOTE:** I don't yet consider this production worthy. There are still bugs in the locking algorithm
+that need to be worked out for it work efficiently. This will be done in the near future.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'throttled_object'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install throttled_object
+
+## Usage
+
+TODO: Add here.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+throttled_object is released under the MIT License (see the [license file](https://github.com/filtersquad/throttled_object/blob/master/LICENSE)) and is copyright Filter Squad, 2012.

data/Rakefile

@@ -0,0 +1,10 @@
+#!/usr/bin/env rake
+require 'rake'
+require 'rspec/core'
+require 'rspec/core/rake_task'
+require 'bundler/gem_tasks'
+
+desc "Run all specs in spec directory"
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/throttled_object.rb

@@ -0,0 +1,12 @@
+require "throttled_object/version"
+
+module ThrottledObject
+  require 'throttled_object/lock'
+  require 'throttled_object/proxy'
+
+  def self.make(object, options = {}, *args)
+    lock = Lock.new(options)
+    Proxy.new object, lock, *args
+  end
+
+end

data/lib/throttled_object/lock.rb

@@ -0,0 +1,82 @@
+require 'redis'
+
+module ThrottledObject
+  class Lock
+
+    class Unavailable < StandardError; end
+
+    KEY_PREFIX = "throttled_object:key:"
+
+    attr_reader :identifier, :amount, :period, :redis
+
+    def initialize(options = {})
+      @identifier = options[:identifier]
+      @amount     = options[:amount]
+      @redis      = options[:redis] || Redis.current
+      _period     = options[:period]
+      raise ArgumentError.new("You must provide an :identifier as a string") unless identifier.is_a?(String)
+      raise ArgumentError.new("You must provide a valid amount of > hits per period") unless amount.is_a?(Numeric) && amount > 0
+      raise ArgumentError.new("You must provide a valid period of > 0 seconds") unless _period.is_a?(Numeric) && _period > 0
+      @period     = (_period.to_f * 1000).ceil
+    end
+
+    # The general locking algorithm is pretty simple. It takes into account two things:
+    #
+    # 1. That we may want to block until it's available (the default)
+    # 2. Occassionally, we need to abort after a short period.
+    #
+    # So, the lock method operates in two methods. The first, and default, we will basically
+    # loop and attempt to aggressively obtain the lock. We loop until we've obtained a lock - 
+    # To obtain the lock, we increment the current periods counter and check if it's <= the max count.
+    # If it is, we have a lock. If not, we sleep until the lock should be 'fresh' again.
+    #
+    # If we're the first one to obtain a lock, we update some book keeping data.
+    def lock(max_time = nil)
+      started_at = current_period
+      has_lock   = false
+      until has_lock
+        now = current_period
+        if max_time && (now - started_at) >= max_time
+          raise Unavailable.new("Unable to obtain a lock after #{now - started_at}ms")
+        end
+        lockable_time = rounded_period now
+        current_key   = KEY_PREFIX + lockable_time.to_s
+        count         = redis.incr current_key
+        if count <= amount
+          has_lock = true
+          # Now we have a lock, we need to actually set the expiration of
+          # the key. Note, we only ever set this on the first set to avoid
+          # setting @amount times...
+          if count == 1
+            # Expire after 3 periods. This means we only
+            # ever keep a small number in memory.
+            expires_after = ((period * 3).to_f / 1000).ceil
+            redis.expire current_key, expires_after
+            redis.setex  "#{current_key}:obtained_at", now, expires_after
+          end
+        else
+          obtained_at = [redis.get("#{current_key}:obtained_at").to_i, lockable_time].max
+          next_period = (lockable_time + period)
+          wait_for    = (next_period - current_period).to_f / 1000
+          sleep wait_for
+        end
+      end
+    end
+
+    def synchronize(*args, &blk)
+      lock *args
+      yield if block_given?
+    end
+
+    private
+
+    def current_period
+      (Time.now.to_f * 1000).ceil
+    end
+
+    def rounded_period(time)
+      (time.to_f / period).ceil * period
+    end
+
+  end
+end

data/lib/throttled_object/proxy.rb

@@ -0,0 +1,25 @@
+require 'delegate'
+
+module ThrottledObject
+  class Proxy < SimpleDelegator
+
+    attr_accessor :lock, :throttled_methods
+
+    def initialize(object, lock, throttled_methods = nil)
+      super object
+      @lock              = lock
+      @throttled_methods = throttled_methods && throttled_methods.map(&:to_sym)
+    end
+
+    private
+
+    def method_missing(m, *args, &block)
+      if throttled_methods.nil? || throttled_methods.include?(m.to_sym)
+        @lock.synchronize { super }
+      else
+        super
+      end
+    end
+
+  end
+end

data/lib/throttled_object/version.rb

@@ -0,0 +1,3 @@
+module ThrottledObject
+  VERSION = "1.0.0"
+end

data/spec/lock_spec.rb

@@ -0,0 +1,30 @@
+require 'spec_helper'
+require 'redis'
+
+describe ThrottledObject::Lock do
+
+  let(:lock) { ThrottledObject::Lock.new identifier: "greeter:#{Process.pid}", amount: 5, period: 1 }
+
+  before :each do
+    lock.redis.flushdb
+  end
+
+  it 'should throttle access under the limit' do
+    expect_to_take(0.0..0.99) { 4.times { lock.lock } }
+  end
+
+  it 'should throttle access equal to the limit' do
+    expect_to_take(0.0..0.99) { 5.times { lock.lock } }
+  end
+
+  it 'correctly throttle access over the limit' do
+    expect_to_take(1.0..1.99) { 6.times { lock.lock } }
+  end
+
+  def expect_to_take(range, &block)
+    start_time = Time.now.to_f
+    yield if block_given?
+    range.should include (Time.now.to_f - start_time)
+  end
+
+end

data/spec/proxy_spec.rb

@@ -0,0 +1,44 @@
+require 'spec_helper'
+
+describe ThrottledObject::Proxy do
+
+  let(:lock) do
+    counter = Struct.new(:value).new(0)
+    def counter.synchronize; self.value += 1; yield if block_given?; end
+    counter
+  end
+
+  let(:target) do
+    Object.new.tap do |o|
+      def o.hello; "World"; end
+      def o.one; 1; end
+      def o.other; nil; end
+    end
+  end
+
+  it 'should let you control which methods invoke it' do
+    proxy = ThrottledObject::Proxy.new target, lock, [:hello]
+    proxy.one.should == 1
+    lock.value.should == 0
+    proxy.other.should == nil
+    lock.value.should == 0
+    proxy.hello.should == "World"
+    lock.value.should == 1
+    proxy.hello.should == "World"
+    lock.value.should == 2
+  end
+
+  it 'should default to requiring all are throttled' do
+    proxy = ThrottledObject::Proxy.new target, lock
+    expect do
+      proxy.one.should == 1
+    end.to change(lock, :value).by(1)
+    expect do
+      proxy.other.should be_nil
+    end.to change(lock, :value).by(1)
+    expect do
+      proxy.hello.should == "World"
+    end.to change(lock, :value).by(1)
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+ENV['REDIS_URL'] ||= "redis://127.0.0.1:6379/#{ENV['REDIS_TEST_DATABASE'] || 9}"
+
+require 'throttled_object'
+
+RSpec.configure do |config| 
+end

data/spec/throttled_object_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+
+describe ThrottledObject do
+
+  it 'should give short hand to create an object' do
+    o = Object.new
+    def o.hello; "world"; end
+    object = ThrottledObject.make o, identifier: "test-object", period: 1, amount: 10
+    object.hello.should == "world"
+    object.lock.should be_a ThrottledObject::Lock
+  end
+
+end

data/throttled_object.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/throttled_object/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Darcy Laycock"]
+  gem.email         = ["darcy@filtersquad.com"]
+  gem.description   = %q{Distributed Object Locks built on Redis.}
+  gem.summary       = %q{Distributed Object Locks built on Redis.}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "throttled_object"
+  gem.require_paths = ["lib"]
+  gem.version       = ThrottledObject::VERSION
+
+  gem.add_dependency 'redis', '~> 3.0'
+  gem.add_development_dependency 'timecop'
+  gem.add_development_dependency 'rspec', '~> 2.0'
+  gem.add_development_dependency 'rake'
+
+end

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: throttled_object
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Darcy Laycock
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-06-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Distributed Object Locks built on Redis.
+email:
+- darcy@filtersquad.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/throttled_object.rb
+- lib/throttled_object/lock.rb
+- lib/throttled_object/proxy.rb
+- lib/throttled_object/version.rb
+- spec/lock_spec.rb
+- spec/proxy_spec.rb
+- spec/spec_helper.rb
+- spec/throttled_object_spec.rb
+- throttled_object.gemspec
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Distributed Object Locks built on Redis.
+test_files:
+- spec/lock_spec.rb
+- spec/proxy_spec.rb
+- spec/spec_helper.rb
+- spec/throttled_object_spec.rb