simple_queues 1.0.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+doc/*

data/.rvmrc

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

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008-2009 François Beausoleil (francois@teksol.info)
+
+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.textile

@@ -0,0 +1,60 @@
+h1. SimpleQueues
+
+In the Gang of Four books, one of the first few lines is "Program to an interface, not an implementation." When you need a queue, the only operations you need are enqueue and dequeue. It doesn't matter that Redis (a nice and simple queue server when you need it) has all kinds of operations available.
+
+This library was written and spec'd on Ruby 1.9.2. It's so small it should work anywhere the Redis gem works.
+
+h2. Exceptions
+
+All underlying exceptions the Redis gem raises are let through: no extra exceptions are raised. This means you'll see <code>Errno::ECONNREFUSED</code>, <code>Errno::EAGAIN</code> and friends.
+
+h2. Usage
+
+<pre><code>require "simple_queues"
+Queues = SimpleQueues::Redis.new
+
+Queues.enqueue :pages_to_crawl, {:url => "http://blog.teksol.info"}.to_json
+Queues.enqueue :pages_to_crawl, {:url => "http://techcrunch.com"}.to_json
+
+# In another process
+
+loop do
+  message = Queues.dequeue_blocking :pages_to_crawl
+  process(message)
+end
+
+# Alternatively, using a timeout
+loop do
+  message = Queues.dequeue_with_timeout :pages_to_crawl, 5 # seconds
+  if message then
+    process(message)
+  else
+    # Timed out
+  end
+end
+<code></pre>
+
+h2. LICENSE
+
+(The MIT License)
+
+Copyright (c) 2008-2009 François Beausoleil (francois@teksol.info)
+
+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/Rakefile

@@ -0,0 +1,19 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+begin
+  require "rspec/core/rake_task"
+  RSpec::Core::RakeTask.new
+
+  task :default => :spec
+rescue LoadError
+  warn "RSpec not available - Rake tasks not available"
+  warn "Install rspec using: gem install rspec"
+end
+
+begin
+  require "yard"
+  YARD::Rake::YardocTask.new(:doc)
+rescue LoadError
+  warn "YARD not available - gem install yard"
+end

data/autotest/discover.rb

@@ -0,0 +1 @@
+Autotest.add_discovery { "rspec2" }

data/lib/simple_queues/redis.rb

@@ -0,0 +1,44 @@
+module SimpleQueues
+  # The Redis version of SimpleQueues.
+  #
+  # Messages are enqueued to the right, dequeued from the left - thus the most recent messages are at the end of the list.
+  class Redis
+    def initialize(redis=Redis.new)
+      @redis = redis
+    end
+
+    # Enqueues a new message to the Redis backend.
+    #
+    # @param queue_name [String, Symbol] The queue name, which must not be nil or the empty String.
+    # @param message [#to_s] The message to be enqueued. The message will be turned into a String through #to_s before being enqueued. Must not be nil, but the empty string is accepted, although it seems meaningless to do so.
+    # @return No useful value.
+    # @raise ArgumentError Whenever the queue name or the message are nil, or the queue name is empty.
+    def enqueue(queue_name, message)
+      raise ArgumentError, "Queue name argument was nil - must not be" if queue_name.nil? || queue_name.to_s.empty?
+      raise ArgumentError, "Message argument was nil - must not be" if message.nil?
+
+      @redis.rpush(queue_name.to_s, message.to_s)
+    end
+
+    # Dequeues a message, and waits forever for one to arrive.
+    #
+    # @param queue_name [String, Symbol] The queue name to read from.
+    # @return [String] The first message in the queue.
+    # @raise ArgumentError If +queue_name+ is nil or the empty String.
+    def dequeue_blocking(queue_name)
+      dequeue_with_timeout(queue_name, 0)
+    end
+
+    # Dequeues a message, or returns +nil+ if the timeout is exceeded.
+    #
+    # @param queue_name [String, Symbol] The queue name to read from.
+    # @param timeout [#to_i] The number of seconds to wait before returning nil.
+    # @return [String, nil] The first message in the queue, or nil if the timeout was exceeded.
+    # @raise ArgumentError If +queue_name+ is nil or the empty String.
+    def dequeue_with_timeout(queue_name, timeout)
+      raise ArgumentError, "Queue name argument was nil - must not be" if queue_name.nil? || queue_name.to_s.empty?
+
+      @redis.blpop(queue_name.to_s, timeout)
+    end
+  end
+end

data/lib/simple_queues/version.rb

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

data/lib/simple_queues.rb

@@ -0,0 +1,14 @@
+# A simple API for queueing and dequeueing messages.
+#
+# In the Gang of Four book, the phrase "Program to an interface, not an implementation" made me think I shouldn't
+# bind my software directly to Redis, but to an API from which I could change the implementation at any time. If
+# I ever need to replace Redis with RabbitMQ, it will be possible to do so, given my software is coded to this
+# interface.
+#
+# All SimpleQueues implementations support three methods:
+# * +enqueue+
+# * +dequeue_with_timeout+
+# * +dequeue_blocking+
+module SimpleQueues
+  autoload :Redis, "simple_queues/redis"
+end

data/simple_queues.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "simple_queues/version"
+
+Gem::Specification.new do |s|
+  s.name        = "simple_queues"
+  s.version     = SimpleQueues::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["François Beausoleil"]
+  s.email       = ["francois@teksol.info"]
+  s.homepage    = "https://github.com/francois/simple_queues"
+  s.summary     = %q{Simple enqueue/dequeue API for working with queues}
+  s.description = %q{Program to an interface, not an implementation - hides Redis (used as a queue) behind a simple interface}
+
+  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"]
+
+  s.add_dependency 'redis'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'RedCloth'
+end

data/spec/dequeueing_spec.rb

@@ -0,0 +1,51 @@
+require "spec_helper"
+
+describe SimpleQueues::Redis, "dequeue_blocking" do
+  let :redis do
+    double("redis")
+  end
+
+  let :queue do
+    SimpleQueues::Redis.new(redis)
+  end
+
+  it "requests an infinite timeout from Redis #blpop" do
+    redis.should_receive(:blpop).with("pages_to_crawl", 0)
+    queue.dequeue_blocking("pages_to_crawl")
+  end
+
+  it "accepts symbols as queue names and translates them to strings" do
+    redis.should_receive(:blpop).with("pages_to_crawl", 0)
+    queue.dequeue_blocking(:pages_to_crawl)
+  end
+
+  it "raises an ArgumentError when the queue name is nil or empty" do
+    lambda { queue.dequeue_blocking(nil) }.should raise_error(ArgumentError)
+    lambda { queue.dequeue_blocking("") }.should raise_error(ArgumentError)
+  end
+end
+
+describe SimpleQueues::Redis, "dequeue_with_timeout" do
+  let :redis do
+    double("redis")
+  end
+
+  let :queue do
+    SimpleQueues::Redis.new(redis)
+  end
+
+  it "should call Redis' BLPOP with the requested timeout" do
+    redis.should_receive(:blpop).with("pages_to_crawl", 42)
+    queue.dequeue_with_timeout(:pages_to_crawl, 42)
+  end
+
+  it "accepts symbols as queue names and translates them to strings" do
+    redis.should_receive(:blpop).with("pages_to_crawl", 5)
+    queue.dequeue_with_timeout(:pages_to_crawl, 5)
+  end
+
+  it "raises an ArgumentError when the queue name is nil or empty" do
+    lambda { queue.dequeue_with_timeout(nil) }.should raise_error(ArgumentError)
+    lambda { queue.dequeue_with_timeout("") }.should raise_error(ArgumentError)
+  end
+end

data/spec/enqueueing_spec.rb

@@ -0,0 +1,40 @@
+require "spec_helper"
+
+describe SimpleQueues::Redis, "enqueue" do
+  let :redis do
+    double("redis")
+  end
+
+  let :queue do
+    SimpleQueues::Redis.new(redis)
+  end
+
+  it "should enqueue to the end of the list" do
+    redis.should_receive(:rpush).with("q", "message")
+    queue.enqueue("q", "message")
+  end
+
+  it "should reject invalid queue names" do
+    lambda { queue.enqueue(nil, "") }.should raise_error(ArgumentError)
+    lambda { queue.enqueue("", "") }.should raise_error(ArgumentError)
+  end
+
+  it "should reject nil messages" do
+    lambda { queue.enqueue(:a, nil) }.should raise_error(ArgumentError)
+  end
+
+  it "should allow blank messages (although does this make sense?)" do
+    redis.should_receive(:rpush)
+    lambda { queue.enqueue(:a, "") }.should_not raise_error
+  end
+
+  it "accepts symbols as queue names, translating to a string" do
+    redis.should_receive(:rpush).with("pages_to_crawl", "http://blog.teksol.info/")
+    queue.enqueue :pages_to_crawl, "http://blog.teksol.info/"
+  end
+
+  it "translates the message to a String before enqueueing" do
+    redis.should_receive(:rpush).with("ops", "shutdown_and_destroy")
+    queue.enqueue :ops, :shutdown_and_destroy
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require "simple_queues"

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification 
+name: simple_queues
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- "Fran\xC3\xA7ois Beausoleil"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-02-26 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: redis
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: RedCloth
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+description: Program to an interface, not an implementation - hides Redis (used as a queue) behind a simple interface
+email: 
+- francois@teksol.info
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .rvmrc
+- Gemfile
+- LICENSE
+- README.textile
+- Rakefile
+- autotest/discover.rb
+- lib/simple_queues.rb
+- lib/simple_queues/redis.rb
+- lib/simple_queues/version.rb
+- simple_queues.gemspec
+- spec/dequeueing_spec.rb
+- spec/enqueueing_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: https://github.com/francois/simple_queues
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+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 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Simple enqueue/dequeue API for working with queues
+test_files: 
+- spec/dequeueing_spec.rb
+- spec/enqueueing_spec.rb
+- spec/spec_helper.rb