beanstalk-client 1.0.2 → 1.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+pkg
+doc
+*.gemspec

data/README.rdoc

@@ -0,0 +1,20 @@
+= Beanstalk Ruby Client
+By: Keith Rarick
+
+Beanstalk is a simple, fast workqueue service. Its interface is generic, but was originally designed for reducing the latency of page views in high-volume web applications by running time-consuming tasks asynchronously.
+
+For more information see:
+- http://kr.github.com/beanstalkd/
+- http://github.com/kr/beanstalkd/blob/master/doc/protocol.txt?raw=true
+
+= Notes
+
+== Multiple Threads
+
+If you want to use this library from multiple concurrent threads, you should synchronize access to the connection. This library does no internal synchronization.
+
+= Contributors
+- Isaac Feliu
+- Peter Kieltyka
+- Martyn Loughran
+- Dustin Sallings

data/Rakefile

@@ -1,4 +1,36 @@
-require 'config/requirements'
-require 'config/hoe' # setup Hoe + all gem configuration
-
-Dir['tasks/**/*.rake'].each { |rake| load rake }
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name        = "beanstalk-client"
+    gem.summary     = "Ruby client for beanstalkd"
+    gem.description = "Ruby client for beanstalkd"
+    gem.email       = "kr@xph.us"
+    gem.homepage    = "http://github.com/kr/beanstalk-client-ruby"
+    gem.authors     = ["Keith Rarick"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title = "beanstalk-client #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.1.0

data/lib/beanstalk-client.rb

@@ -24,3 +24,5 @@ module Beanstalk
 end
 
 require 'beanstalk-client/connection'
+require 'beanstalk-client/errors'
+require 'beanstalk-client/job'

data/lib/beanstalk-client/connection.rb

@@ -19,14 +19,14 @@ require 'socket'
 require 'fcntl'
 require 'yaml'
 require 'set'
-require 'beanstalk-client/errors'
-require 'beanstalk-client/job'
+require 'thread'
 
 module Beanstalk
   class Connection
     attr_reader :addr
 
     def initialize(addr, default_tube=nil)
+      @mutex = Mutex.new
       @waiting = false
       @addr = addr
       connect
@@ -50,6 +50,10 @@ module Beanstalk
     end
 
     def put(body, pri=65536, delay=0, ttr=120)
+      pri = pri.to_i
+      delay = delay.to_i
+      ttr = ttr.to_i
+      body = body.to_s # Make sure that body.size gives a useful number
       interact("put #{pri} #{delay} #{ttr} #{body.size}\r\n#{body}\r\n",
                %w(INSERTED BURIED))[0].to_i
     end
@@ -76,6 +80,7 @@ module Beanstalk
 
     def reserve(timeout=nil)
       raise WaitingForJobError if @waiting
+      @mutex.lock
       if timeout.nil?
         @socket.write("reserve\r\n")
       else
@@ -93,6 +98,8 @@ module Beanstalk
       end
 
       Job.new(self, *read_job('RESERVED'))
+    ensure
+      @mutex.unlock
     end
 
     def delete(id)
@@ -101,6 +108,9 @@ module Beanstalk
     end
 
     def release(id, pri, delay)
+      id = id.to_i
+      pri = pri.to_i
+      delay = delay.to_i
       interact("release #{id} #{pri} #{delay}\r\n", %w(RELEASED))
       :ok
     end
@@ -110,6 +120,15 @@ module Beanstalk
       :ok
     end
 
+    def touch(id)
+      interact("touch #{id}\r\n", %w(TOUCHED))
+      :ok
+    end
+
+    def kick(n)
+      interact("kick #{n}\r\n", %w(KICKED))[0].to_i
+    end
+
     def use(tube)
       return tube if tube == @last_used
       @last_used = interact("use #{tube}\r\n", %w(USING))[0]
@@ -162,10 +181,13 @@ module Beanstalk
 
     def interact(cmd, rfmt)
       raise WaitingForJobError if @waiting
+      @mutex.lock
       @socket.write(cmd)
       return read_yaml('OK') if rfmt == :yaml
       return found_job if rfmt == :job
       check_resp(*rfmt)
+    ensure
+      @mutex.unlock
     end
 
     def get_resp()
@@ -193,7 +215,7 @@ module Beanstalk
       id, bytes = check_resp(word).map{|s| s.to_i}
       body = read_bytes(bytes)
       raise 'bad trailer' if read_bytes(2) != "\r\n"
-      [id, body]
+      [id, body, word == 'RESERVED']
     end
 
     def read_yaml(word)
@@ -233,9 +255,10 @@ module Beanstalk
             @watch_list.each{|tube| @connections[addr].watch(tube)}
             to_ignore.each{|tube| @connections[addr].ignore(tube)}
           end
+        rescue Errno::ECONNREFUSED
+          raise NotConnected
         rescue Exception => ex
           puts "#{ex.class}: #{ex}"
-          #puts begin ex.fixed_backtrace rescue ex.backtrace end
         end
       end
       @connections.size
@@ -249,14 +272,28 @@ module Beanstalk
       @last_conn.addr
     end
 
+    # Put a job on the queue.
+    #
+    # == Parameters:
+    #
+    # * <tt>body</tt>: the payload of the job (use Beanstalk::Pool#yput / Beanstalk::Job#ybody to automatically serialize your payload with YAML)
+    # * <tt>pri</tt>: priority. Default 65536 (higher numbers are higher priority)
+    # * <tt>delay</tt>: how long to wait until making the job available for reservation
+    # * <tt>ttr</tt>: time in seconds for the job to reappear on the queue (if beanstalk doesn't hear from a consumer within this time, assume the consumer died and make the job available for someone else to process).  Default 120 seconds.
     def put(body, pri=65536, delay=0, ttr=120)
       send_to_rand_conn(:put, body, pri, delay, ttr)
     end
 
+    # Like put, but serialize the object with YAML.
     def yput(obj, pri=65536, delay=0, ttr=120)
       send_to_rand_conn(:yput, obj, pri, delay, ttr)
     end
 
+    # Reserve a job from the queue.
+    #
+    # == Parameters
+    #
+    # * <tt>timeout</tt> - Time (in seconds) to wait for a job to be available. If nil, wait indefinitely.
     def reserve(timeout=nil)
       send_to_rand_conn(:reserve, timeout)
     end
@@ -306,9 +343,12 @@ module Beanstalk
     end
 
     def remove(conn)
-      @connections.delete(conn.addr)
+      connection = @connections.delete(conn.addr)
+      connection.close if connection
+      connection
     end
 
+    # Close all open connections for this pool
     def close
       while @connections.size > 0
         addr = @connections.keys.last
@@ -339,7 +379,9 @@ module Beanstalk
     def call_wrap(c, *args)
       self.last_conn = c
       c.send(*args)
-    rescue EOFError, Errno::ECONNRESET, Errno::EPIPE, UnexpectedResponse => ex
+    rescue UnexpectedResponse => ex
+      raise ex
+    rescue EOFError, Errno::ECONNRESET, Errno::EPIPE => ex
       self.remove(c)
       raise ex
     end

data/lib/beanstalk-client/job.rb

@@ -36,28 +36,42 @@ class Beanstalk::Job
     (@ybody ||= [begin YAML.load(body) rescue nil end])[0]
   end
 
-  def initialize(conn, id, body)
+  def initialize(conn, id, body, reserved=true)
     @conn = conn
     @id = id
     @body = body
-    @deleted = false
+    @reserved = reserved
   end
 
+  # Deletes the job from the queue
   def delete()
-    @conn.delete(id) if !@deleted
-    @deleted = true
+    return if !@reserved
+    @conn.delete(id)
+    @reserved = false
   end
 
+
   def put_back(pri=self.pri, delay=0, ttr=self.ttr)
     @conn.put(body, pri, delay, ttr)
   end
 
-  def release(newpri=pri, delay=0)
-    @conn.release(id, newpri, delay)
+  # Releases the job back to the queue so another consumer can get it (call this if the job failed and want it to be tried again)
+  def release(newpri=nil, delay=0)
+    return if !@reserved
+    @conn.release(id, newpri || pri, delay)
+    @reserved = false
+  end
+
+  def bury(newpri=nil)
+    return if !@reserved
+    @conn.bury(id, newpri || pri)
+    @reserved = false
   end
 
-  def bury(newpri=pri)
-    @conn.bury(id, newpri)
+  # Ping beanstalkd to to tell it you're alive and processing. If beanstalkd doesn't hear from you for more than the ttr seconds (specified by the put command), then it assumes the consumer died and reinserts the job back into the queue for another to process.
+  def touch
+    return if !@reserved
+    @conn.touch(id)
   end
 
   def stats()
@@ -65,6 +79,8 @@ class Beanstalk::Job
   end
 
   def timeouts() stats['timeouts'] end
+
+  # Time left (in seconds) that beanstalk has to process the job. When this time expires, beanstalkd automatically reinserts the job in the queue.  See the ttr parameter for Beanstalk::Pool#put
   def time_left() stats['time-left'] end
   def age() stats['age'] end
   def state() stats['state'] end

data/lib/beanstalk-client/version.rb

@@ -1,5 +1,3 @@
 module Beanstalk #:nodoc:
-  module VERSION #:nodoc:
-    STRING = '1.0.2'
-  end
+  VERSION = '1.0.3'
 end

data/test/helper.rb

@@ -0,0 +1,9 @@
+require 'rubygems'
+require 'test/unit'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'beanstalk-client'
+
+class Test::Unit::TestCase
+end

data/test/test_beanstalk-client.rb

@@ -1,12 +1,7 @@
-require File.dirname(__FILE__) + '/test_helper.rb'
-
-require 'beanstalk-client'
-
-class TestBeanstalk < Test::Unit::TestCase
-  def setup
-  end
-
-  def test_truth
-    assert true
-  end
-end
+require 'helper'
+
+class TestBeanstalkClient < Test::Unit::TestCase
+  def test_truth
+    assert true
+  end
+end

metadata

@@ -1,78 +1,84 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.9.4
-specification_version: 1
 name: beanstalk-client
 version: !ruby/object:Gem::Version 
-  version: 1.0.2
-date: 2008-06-18 00:00:00 -07:00
-summary: Ruby client library for the Beanstalk protocol
-require_paths: 
-- lib
-email: kr@causes.com
-homepage: http://beanstalk.rubyforge.org
-rubyforge_project: beanstalk
-description: Ruby client library for the Beanstalk protocol
-autorequire: 
-default_executable: 
-bindir: bin
-has_rdoc: true
-required_ruby_version: !ruby/object:Gem::Version::Requirement 
-  requirements: 
-  - - ">"
-    - !ruby/object:Gem::Version 
-      version: 0.0.0
-  version: 
+  hash: 19
+  prerelease: false
+  segments: 
+  - 1
+  - 1
+  - 0
+  version: 1.1.0
 platform: ruby
-signing_key: 
-cert_chain: 
-post_install_message: 
 authors: 
 - Keith Rarick
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-20 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Ruby client for beanstalkd
+email: kr@xph.us
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
 files: 
-- History.txt
-- License.txt
-- Manifest.txt
-- README.txt
+- .gitignore
+- LICENSE
+- README.rdoc
 - Rakefile
-- config/hoe.rb
-- config/requirements.rb
+- VERSION
 - lib/beanstalk-client.rb
 - lib/beanstalk-client/connection.rb
 - lib/beanstalk-client/errors.rb
 - lib/beanstalk-client/job.rb
 - lib/beanstalk-client/version.rb
-- log/debug.log
-- script/destroy
-- script/generate
-- script/txt2html
-- setup.rb
-- tasks/deployment.rake
-- tasks/environment.rake
-- tasks/website.rake
+- test/helper.rb
 - test/test_beanstalk-client.rb
-- test/test_helper.rb
-- website/index.html
 - website/index.txt
 - website/javascripts/rounded_corners_lite.inc.js
 - website/stylesheets/screen.css
 - website/template.rhtml
-test_files: 
-- test/test_beanstalk-client.rb
-- test/test_helper.rb
-rdoc_options: 
-- --main
-- README.txt
-extra_rdoc_files: 
-- History.txt
-- License.txt
-- Manifest.txt
-- README.txt
-- website/index.txt
-executables: []
-
-extensions: []
+has_rdoc: true
+homepage: http://github.com/kr/beanstalk-client-ruby
+licenses: []
 
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
 requirements: []
 
-dependencies: []
-
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Ruby client for beanstalkd
+test_files: 
+- test/helper.rb
+- test/test_beanstalk-client.rb