delay_queue 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rspec

@@ -0,0 +1 @@
+--color

data/.rvmrc

@@ -0,0 +1 @@
+rvm use 1.9.2@delay_queue

data/Gemfile

@@ -0,0 +1,11 @@
+source :rubygems
+
+gem 'redis', '>= 2.2.0'
+
+group :development do
+  gem 'rspec', '~> 2.3.0'
+  gem 'bundler', '~> 1.0.0'
+  gem 'jeweler', '~> 1.6.4'
+  gem 'rcov', '>= 0'
+  gem 'ruby-debug19', :require => 'ruby-debug'
+end

data/Gemfile.lock

@@ -0,0 +1,45 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    archive-tar-minitar (0.5.2)
+    columnize (0.3.4)
+    diff-lcs (1.1.3)
+    git (1.2.5)
+    jeweler (1.6.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+    linecache19 (0.5.12)
+      ruby_core_source (>= 0.1.4)
+    rake (0.9.2.2)
+    rcov (0.9.11)
+    redis (2.2.2)
+    rspec (2.3.0)
+      rspec-core (~> 2.3.0)
+      rspec-expectations (~> 2.3.0)
+      rspec-mocks (~> 2.3.0)
+    rspec-core (2.3.1)
+    rspec-expectations (2.3.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.3.0)
+    ruby-debug-base19 (0.11.25)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby_core_source (>= 0.1.4)
+    ruby-debug19 (0.11.6)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby-debug-base19 (>= 0.11.19)
+    ruby_core_source (0.1.5)
+      archive-tar-minitar (>= 0.5.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  jeweler (~> 1.6.4)
+  rcov
+  redis (>= 2.2.0)
+  rspec (~> 2.3.0)
+  ruby-debug19

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+Copyright (c) 2011 Daniel W. Nelson
+Development sponsored by Centresource, Inc.
+
+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,74 @@
+DelayQueue
+==========
+
+DelayQueue provides a thread safe, Redis backed queue with two simple properties:
+
+1. items may be queued with a delay so that they can't be dequeued until some time in the future
+2. each item in the queue is unique
+
+
+Use Cases
+=========
+
+Throttling
+----------
+
+For example, if you want to send notifications to users when something happens, but you don't want users to be flooded with notifications (eg: bug report emails), you could put a user id into a 'bug_notifications' queue every time a bug occurs, setting the dequeue time to @user.last_notified_at + MAX_NOTIFY_FREQUENCY. The uniqueness constraint ensures that the user only gets added once until it is next dequeued, while the time constraint ensures that the user id will only be dequeued once per MAX_NOTIFY_FREQUENCY.
+
+External Resources
+------------------
+
+If you are communicating with an external resource, and that resource is down, you will want to re-queue the job, but you don't want to hit the resource right away. Maybe wait a minute before trying again. If the resource is still down, wait longer. This prevents your system from getting caught up processing jobs that can't complete and is also considerate of the external resource that may be choking under heavy load and won't benefit from a worker continually trying to hit the resource again.
+
+
+
+Usage
+=====
+
+In your Gemfile:
+
+    gem 'delay_queue'
+
+Example:
+
+    $ irb
+    require 'redis'
+    require 'delay_queue'
+    redis = Redis.new(:host => '127.0.0.1', :port => '6379')
+    queue = DelayQueue.new(redis, 'bug_notification_queue')
+    queue.enqueue('123')
+    queue.dequeue
+      - '123'
+
+    queue.enqueue('123', :delay => 3)
+    queue.dequeue
+      - nil
+    sleep 3
+    queue.dequeue
+      - '123'
+
+    queue.enqueue('123', :until => Time.now + 3)
+    queue.dequeue
+      - nil
+    sleep 3
+    queue.dequeue
+      - '123'
+
+    queue.enqueue('123')
+    queue.enqueue('123')
+    queue.dequeue
+      - '123'
+    queue.dequeue
+      - nil
+
+
+Contributing to delay_queue
+==========================
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add specs for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

data/Rakefile

@@ -0,0 +1,50 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "delay_queue"
+  gem.homepage = "http://github.com/centresource/delay_queue"
+  gem.license = "MIT"
+  gem.summary = %Q{A thread safe, Redis backed queue with the ability to delay items from being dequeued}
+  gem.description = %Q{A thread safe, Redis backed queue with the ability to delay items from being dequeued}
+  gem.email = "dnelson@centresource.com"
+  gem.authors = ["Daniel Nelson"]
+  # dependencies defined in Gemfile
+  gem.files.exclude 'spec'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "delay_queue #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/delay_queue.gemspec

@@ -0,0 +1,67 @@
+# 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 = "delay_queue"
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Daniel Nelson"]
+  s.date = "2011-11-04"
+  s.description = "A thread safe, Redis backed queue with the ability to delay items from being dequeued"
+  s.email = "dnelson@centresource.com"
+  s.extra_rdoc_files = [
+    "LICENSE",
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+    ".rspec",
+    ".rvmrc",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "delay_queue.gemspec",
+    "lib/delay_queue.rb",
+    "spec/delay_queue_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = "http://github.com/centresource/delay_queue"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.10"
+  s.summary = "A thread safe, Redis backed queue with the ability to delay items from being dequeued"
+
+  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<redis>, [">= 2.2.0"])
+      s.add_development_dependency(%q<rspec>, ["~> 2.3.0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.6.4"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+      s.add_development_dependency(%q<ruby-debug19>, [">= 0"])
+    else
+      s.add_dependency(%q<redis>, [">= 2.2.0"])
+      s.add_dependency(%q<rspec>, ["~> 2.3.0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+      s.add_dependency(%q<ruby-debug19>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<redis>, [">= 2.2.0"])
+    s.add_dependency(%q<rspec>, ["~> 2.3.0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.6.4"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+    s.add_dependency(%q<ruby-debug19>, [">= 0"])
+  end
+end
+

data/lib/delay_queue.rb

@@ -0,0 +1,71 @@
+class DelayQueue
+
+  def initialize(redis, queue_name)
+    @redis = redis
+    @queue_name = queue_name
+    @lock_name = 'lock.' + @queue_name
+  end
+
+  def delete_all!
+    @redis.zremrangebyrank(@queue_name, 0, -1)
+  end
+
+  def empty?
+    size == 0
+  end
+
+  def size
+    @redis.zcard(@queue_name)
+  end
+
+  # Enqueue a unique item with an optional delay
+  #
+  # <tt>:item</tt>:: A string
+  # <tt>:options</tt>:: An optional hash of one of the following options
+  #   <tt>:until</tt>:: Time before which not to allow this item to be dequeued
+  #   <tt>:delay</tt>:: Number of seconds to wait before allowing this to be dequeued
+  #
+  def enqueue(item, options={ :delay => 0})
+    if options[:delay]
+      time = Time.now + options[:delay]
+    elsif options[:until]
+      time = options[:until]
+    end
+    @redis.zadd(@queue_name, time.to_i, item)
+  end
+
+  def dequeue
+    if acquire_lock || break_lock
+      array = @redis.zrangebyscore(@queue_name, 0, Time.now.to_i, :limit => [0, 1])
+      item = array.first if array
+      @redis.zrem(@queue_name, item) if item
+      release_lock
+      item
+    else # couldn't acquire or break the lock. wait and try again
+      sleep 1
+      dequeue
+    end
+  end
+
+  def acquire_lock # :nodoc:
+    @redis.setnx(@lock_name, new_lock_expiration)
+  end
+
+  def release_lock # :nodoc:
+    @redis.del(@lock_name)
+  end
+
+  def break_lock # :nodoc:
+    previous = @redis.getset(@lock_name, new_lock_expiration)
+    previous.nil? || Time.at(previous.to_i) <= Time.now
+  end
+
+  private
+
+  LOCK_DURATION = 3
+
+  def new_lock_expiration
+    (Time.now + LOCK_DURATION).to_i
+  end
+
+end

data/spec/delay_queue_spec.rb

@@ -0,0 +1,207 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "DelayQueue" do
+  before(:each) do
+    redis = Redis.new(:host => '127.0.0.1', :port => '6379')
+    @queue = DelayQueue.new(redis, 'test_delay_queue')
+  end
+
+  after(:each) do
+    @queue.delete_all!
+  end
+
+  describe "#enqueue" do
+    it "should enable the specification of a time before which the item may not be dequeued" do
+      @queue.enqueue('a', :until => Time.now + 2)
+      sleep 1
+      @queue.dequeue.should be_nil
+      sleep 2
+      @queue.dequeue.should == 'a'
+    end
+
+    it "should enable the specification of a delay to wait before releasing the item from the queue" do
+      @queue.enqueue('a', :delay => 2)
+      sleep 1
+      @queue.dequeue.should be_nil
+      sleep 2
+      @queue.dequeue.should == 'a'
+    end
+
+    context "when no options are provided" do
+      it "should not delay the item from being dequeued" do
+        @queue.enqueue('a')
+        @queue.dequeue.should == 'a'
+      end
+    end
+    
+    context "enqueing an item more than once" do
+      it "should not add the item a second time" do
+        @queue.enqueue('a')
+        @queue.enqueue('a', :delay => 60)
+        @queue.size.should == 1
+      end
+
+      it "should update the time at which to enable the item to be dequeued" do
+        @queue.enqueue('a')
+        @queue.enqueue('a', :delay => 60)
+        @queue.should_not be_empty
+        @queue.dequeue.should be_nil
+
+        @queue.delete_all!
+
+        @queue.enqueue('a', :delay => 60)
+        @queue.enqueue('a')
+        @queue.dequeue.should == 'a'
+      end
+    end
+  end
+
+  describe "#delete_all!" do
+    it "should remove all elements from the queue, whether or not they are ready to be dequeued" do
+      @queue.enqueue('test')
+      @queue.should_not be_empty
+      @queue.delete_all!
+      @queue.should be_empty
+    end
+  end
+
+  describe "#acquire_lock" do
+    after(:each) do
+      @queue.release_lock
+    end
+
+    context "when the lock is not already taken" do
+      it "should return true" do
+        @queue.acquire_lock.should be_true
+      end
+
+      it "should lock the resource" do
+        @queue.acquire_lock
+        @queue.acquire_lock.should be_false
+      end
+    end
+
+    context "when the lock is already taken" do
+      it "should return false" do
+        @queue.acquire_lock
+        @queue.acquire_lock.should be_false
+      end
+    end
+  end
+
+  describe "#break_lock" do
+    after(:each) do
+      @queue.release_lock
+    end
+
+    context "when the lock is not already taken" do
+      it "should be true" do
+        @queue.break_lock.should be_true
+      end
+
+      it "should lock the resource" do
+        @queue.break_lock
+        @queue.acquire_lock.should be_false
+      end
+    end
+
+    context "when the lock is taken and not yet expired" do
+      it "should be false" do
+        @queue.acquire_lock
+        @queue.break_lock.should be_false
+      end
+    end
+
+    context "when the lock is taken, but expired" do
+      it "should be true" do
+        @queue.acquire_lock
+        sleep(3)
+        @queue.break_lock.should be_true
+      end
+
+      it "should lock the resource" do
+        @queue.acquire_lock
+        sleep(3)
+        @queue.break_lock
+        @queue.acquire_lock.should be_false
+      end
+    end
+
+    it "should be able to break an expired lock acquired through breaking a lock" do
+      @queue.break_lock
+      sleep(3)
+      @queue.break_lock.should be_true
+    end
+  end
+
+  describe "#dequeue" do
+    context "when the queue is empty" do
+      it "should return nil" do
+        @queue.dequeue.should be_nil
+      end
+    end
+
+    context "when the queue has an element that is not ready to be dequeued" do
+      it "should return nil" do
+        @queue.enqueue('a', :delay => 2)
+        @queue.dequeue.should be_nil
+      end
+    end
+
+    context "when the queue has an element that is ready to be dequeued" do
+      it "should return that element" do
+        @queue.enqueue('a', :delay => 0)
+        @queue.dequeue.should == 'a'
+      end
+
+      it "should remove that element from the queue" do
+        @queue.enqueue('a', :delay => 0)
+        @queue.dequeue.should == 'a'
+        @queue.should be_empty
+      end
+    end
+  end
+
+  describe "#size" do
+    context "when the queue is empty" do
+      it "should be 0" do
+        @queue.size.should == 0
+      end
+    end
+
+    context "when the queue has N elements, regardless of whether or not they are ready to be dequeued" do
+      it "should match the number of elements" do
+        @queue.enqueue('a')
+        @queue.size.should == 1
+
+        @queue.enqueue('b', :delay => 60)
+        @queue.size.should == 2
+
+        @queue.enqueue('c')
+        @queue.size.should == 3
+      end
+    end
+  end
+
+  describe "#empty?" do
+    context "when the queue is empty" do
+      it "should be true" do
+        @queue.should be_empty
+      end
+    end
+
+    context "when the queue has an element that is not ready to be dequeued" do
+      it "should be false" do
+        @queue.enqueue('a', :delay => 0)
+        @queue.should_not be_empty
+      end
+    end
+
+    context "when the queue has an element that is ready to be dequeued" do
+      it "should be false" do
+        @queue.enqueue('a', :delay => 0)
+        @queue.should_not be_empty
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,15 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rspec'
+require 'delay_queue'
+require 'bundler'
+Bundler.require
+require 'ruby-debug'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: delay_queue
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Daniel Nelson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-11-04 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: &2169330560 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *2169330560
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &2169330020 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+  type: :development
+  prerelease: false
+  version_requirements: *2169330020
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: &2169329440 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *2169329440
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: &2169328840 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.6.4
+  type: :development
+  prerelease: false
+  version_requirements: *2169328840
+- !ruby/object:Gem::Dependency
+  name: rcov
+  requirement: &2169328240 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2169328240
+- !ruby/object:Gem::Dependency
+  name: ruby-debug19
+  requirement: &2169327640 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2169327640
+description: A thread safe, Redis backed queue with the ability to delay items from
+  being dequeued
+email: dnelson@centresource.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE
+- README.md
+files:
+- .document
+- .rspec
+- .rvmrc
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- VERSION
+- delay_queue.gemspec
+- lib/delay_queue.rb
+- spec/delay_queue_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/centresource/delay_queue
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 4129610326982047189
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: A thread safe, Redis backed queue with the ability to delay items from being
+  dequeued
+test_files: []