stalk_climber 0.0.2 → 0.0.3

data/lib/stalk_climber/climber.rb

@@ -15,9 +15,30 @@ module StalkClimber
     end
 
 
+    # Climb over all jobs on all connections in the connection pool.
+    # An instance of Job is yielded. For more information see Connection#climb
+    def climb
+      enum = to_enum
+      return enum unless block_given?
+      loop do
+        begin
+          yield enum.next
+        rescue StopIteration
+          return ($ERROR_INFO.nil? || $ERROR_INFO.result.nil?) ? nil : $ERROR_INFO.result
+        end
+      end
+    end
+    alias_method :each, :climb
+
+
     # Perform a threaded climb across all connections in the connection pool.
+    # This method cannot be used for enumerable enumeration because a break
+    # called from one of the threads will cause a LocalJumpError. This could be
+    # fixed, but expected behavior on break varies as to whether or not to wait
+    # for all threads before returning a result. However, still useful for
+    # operations that always visit all jobs.
     # An instance of Job is yielded to +block+
-    def climb(&block)
+    def climb_threaded(&block)
       threads = []
       self.connection_pool.connections.each do |connection|
         threads << Thread.new { connection.each(&block) }
@@ -25,7 +46,7 @@ module StalkClimber
       threads.each(&:join)
       return
     end
-    alias_method :each, :climb
+    alias_method :each_threaded, :climb_threaded
 
 
     # Creates a new Climber instance, optionally yielding the instance
@@ -36,5 +57,29 @@ module StalkClimber
       yield(self) if block_given?
     end
 
+
+    # Returns a hash with connections as keys and max_job_ids as values
+    def max_job_ids
+      connection_pairs = connection_pool.connections.map do |connection|
+        [connection, connection.max_job_id]
+      end
+      return Hash[connection_pairs]
+    end
+
+
+    # Returns an Enumerator for enumerating jobs on all connections.
+    # Connections are enumerated in the order defined. See Connection#to_enum
+    # for more information
+    # A job is yielded with each iteration.
+    def to_enum
+      return Enumerator.new do |yielder|
+        self.connection_pool.connections.each do |connection|
+          connection.each do |job|
+            yielder << job
+          end
+        end
+      end
+    end
+
   end
 end

data/lib/stalk_climber/connection.rb

@@ -1,6 +1,6 @@
 module StalkClimber
   class Connection < Beaneater::Connection
-    include LazyEnumerable
+    include RUBY_VERSION >= '2.0.0' ? LazyEnumerable : Enumerable
 
     DEFAULT_TUBE = 'stalk_climber'
     PROBE_TRANSMISSION = "put 4294967295 0 300 2\r\n{}"
@@ -22,15 +22,57 @@ module StalkClimber
     end
 
 
-    # Handles job enumeration in descending ID order, passing an instance of Job to +block+ for
-    # each existing job on the beanstalk server. Jobs are enumerated in three phases. Jobs between
-    # max_job_id and the max_climbed_job_id are pulled from beanstalk, cached, and given to
-    # +block+. Jobs that have already been cached are yielded to +block+ if they still exist,
-    # otherwise they are deleted from the cache. Finally, jobs between min_climbed_job_id and 1
-    # are pulled from beanstalk, cached, and given to +block+.
+    # Interface for job enumerator/enumeration in descending ID order. Returns an instance of
+    # Job for each existing job on the beanstalk server. Jobs are enumerated in three phases. Jobs
+    # between max_job_id and the max_climbed_job_id are pulled from beanstalk, cached, and yielded.
+    # Jobs that have already been cached are yielded if they still exist, otherwise they are deleted
+    # from the cache. Finally, jobs between min_climbed_job_id and 1 are pulled from beanstalk, cached,
+    # and yielded.
     # Connection#each fulfills Enumberable contract, allowing connection to behave as an Enumerable.
-    def each(&block)
-      climb(&block)
+    def climb
+      enum = to_enum
+      return enum unless block_given?
+      loop do
+        begin
+          yield enum.next
+        rescue StopIteration
+          return ($ERROR_INFO.nil? || $ERROR_INFO.result.nil?) ? nil : $ERROR_INFO.result
+        end
+      end
+    end
+    alias_method :each, :climb
+
+
+    # Safe form of fetch_job!, returns a Job instance for the specified +job_id+.
+    # If the job does not exist, the error is caught and nil is passed returned instead.
+    def fetch_job(job_id)
+      begin
+        job = fetch_job!(job_id)
+      rescue Beaneater::NotFoundError
+        job = nil
+      end
+      return job
+    end
+
+
+    # Returns a Job instance for the specified +job_id+. If the job does not exist,
+    # a Beaneater::NotFoundError will bubble up from Beaneater. The job is not cached.
+    def fetch_job!(job_id)
+      return Job.new(transmit("peek #{job_id}"))
+    end
+
+
+    # Like fetch_job, but fetches all job ids in +job_ids+. Jobs are not cached and
+    # nil is returned if any of the jobs don't exist.
+    def fetch_jobs(*job_ids)
+      return job_ids.flatten.map { |job_id| fetch_job(job_id) }
+    end
+
+
+    # Similar to fetch_job!, but fetches all job ids in +job_ids+. Jobs are not cached
+    # and a Beaneater::NotFoundError is raised if any of the listed jobs don't exist.
+    def fetch_jobs!(*job_ids)
+      return job_ids.flatten.map { |job_id| fetch_job!(job_id) }
     end
 
 
@@ -68,63 +110,47 @@ module StalkClimber
     end
 
 
-    # Safe form of with_job!, yields a Job instance to +block+ for the specified +job_id+.
-    # If the job does not exist, the error is caught and nil is passed to +block+ instead.
-    def with_job(job_id, &block)
-      begin
-        with_job!(job_id, &block)
-      rescue Beaneater::NotFoundError
-        block.call(nil)
-      end
-    end
+    # Returns an Enumerator for crawling all existing jobs for a connection.
+    # See Connection#each for more information.
+    def to_enum
+      return Enumerator.new do |yielder|
+        max_id = max_job_id
 
+        initial_cached_jobs = cache.values_at(*cache.keys.sort.reverse)
 
-    # Yields a Job instance to +block+ for the specified +job_id+.
-    # If the job does not exist, a Beaneater::NotFoundError will bubble up from Beaneater.
-    def with_job!(job_id, &block)
-      job = Job.new(transmit("peek #{job_id}"))
-      block.call(job)
-    end
-
+        max_id.downto(self.max_climbed_job_id + 1) do |job_id|
+          job = fetch_and_cache_job(job_id)
+          yielder << job unless job.nil?
+        end
 
-    protected
+        initial_cached_jobs.each do |job|
+          if job.exists?
+            yielder << job
+          else
+            self.cache.delete(job.id)
+          end
+        end
 
-    # Helper method, similar to with_job, that retrieves the job identified by
-    # +job_id+, caches it, and  updates counters before yielding the job.
-    # If the job does not exist, +block+ is not called and nothing is cached,
-    # however counters will be updated.
-    def cache_job_and_yield(job_id, &block)
-      with_job(job_id) do |job|
-        self.cache[job_id] = job unless job.nil?
-        @min_climbed_job_id = job_id if job_id < @min_climbed_job_id
-        @max_climbed_job_id = job_id if job_id > @max_climbed_job_id
-        yield(job) unless job.nil?
+        ([self.min_climbed_job_id - 1, max_id].min).downto(1) do |job_id|
+          job = fetch_and_cache_job(job_id)
+          yielder << job unless job.nil?
+        end
       end
     end
 
 
-    # Handles job enumeration. See Connection#each for more information.
-    def climb(&block)
-      max_id = max_job_id
-
-      initial_cached_jobs = cache.values_at(*cache.keys.sort.reverse)
-
-      max_id.downto(self.max_climbed_job_id + 1) do |job_id|
-        cache_job_and_yield(job_id, &block)
-      end
-
-      initial_cached_jobs.each do |job|
-        if job.exists?
-          yield job
-        else
-          self.cache.delete(job.id)
-        end
-      end
+    protected
 
-      ([self.min_climbed_job_id - 1, max_id].min).downto(1) do |job_id|
-        cache_job_and_yield(job_id, &block)
-      end
-      return
+    # Helper method, similar to fetch_job, that retrieves the job identified by
+    # +job_id+, caches it, and updates counters before returning the job.
+    # If the job does not exist, nothing is cached, however counters will be updated,
+    # and nil is returned
+    def fetch_and_cache_job(job_id)
+      job = fetch_job(job_id)
+      self.cache[job_id] = job unless job.nil?
+      @min_climbed_job_id = job_id if job_id < @min_climbed_job_id
+      @max_climbed_job_id = job_id if job_id > @max_climbed_job_id
+      return job
     end
 
 

data/lib/stalk_climber/job.rb

@@ -15,7 +15,7 @@ module StalkClimber
 
     # Returns or fetches the body of the job obtained via the peek command
     def body
-      return @body ||= JSON.parse(connection.transmit("peek #{id}")[:body])
+      return @body ||= connection.transmit("peek #{id}")[:body]
     end
 
 
@@ -28,6 +28,7 @@ module StalkClimber
     # Deletes the job from beanstalk. If the job is not found it is assumed that it
     # has already been otherwise deleted.
     def delete
+      return true if @status == 'DELETED'
       begin
         @connection.transmit("delete #{id}")
       rescue Beaneater::NotFoundError
@@ -45,6 +46,7 @@ module StalkClimber
     # the job, the peek command could return a much larger response. Rather than waste
     # the trip to the server, stats are updated each time the method is called.
     def exists?
+      return false if @status == 'DELETED'
       begin
         stats(:force_refresh)
         return true
@@ -76,7 +78,7 @@ module StalkClimber
         @body = @stats = nil
       when 'FOUND' # peek
         @id = job_data[:id].to_i
-        @body = JSON.parse(job_data[:body])
+        @body = job_data[:body]
         @stats = nil
       when 'OK' # stats-job
         @body = nil

data/lib/stalk_climber/version.rb

@@ -1,3 +1,3 @@
 module StalkClimber
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end

data/test/unit/climber_test.rb

@@ -2,7 +2,7 @@ require 'test_helper'
 
 class ClimberTest < Test::Unit::TestCase
 
-  def test_climb_caches_jobs_for_later_use
+  def test_each_caches_jobs_for_later_use
     climber = StalkClimber::Climber.new(BEANSTALK_ADDRESSES)
 
     test_jobs = {}
@@ -30,6 +30,35 @@ class ClimberTest < Test::Unit::TestCase
   end
 
 
+  def test_each_threaded_works_for_non_break_situation
+    climber = StalkClimber::Climber.new(BEANSTALK_ADDRESSES)
+    test_jobs = {}
+    climber.connection_pool.connections.each do |connection|
+      test_jobs[connection.address] = []
+      5.times.to_a.map! do
+          test_jobs[connection.address] << StalkClimber::Job.new(connection.transmit(StalkClimber::Connection::PROBE_TRANSMISSION))
+      end
+    end
+
+    assert_raise LocalJumpError do
+      climber.each_threaded do |job|
+        break
+      end
+    end
+
+    assert_nothing_raised do
+      # test normal enumeration
+      climber.each_threaded do |job|
+        job
+      end
+    end
+
+    climber.connection_pool.connections.each do |connection|
+      test_jobs[connection.address].map(&:delete)
+    end
+  end
+
+
   def test_connection_pool_creates_a_connection_pool
     climber = StalkClimber::Climber.new('beanstalk://localhost')
     assert_kind_of StalkClimber::ConnectionPool, climber.connection_pool
@@ -44,6 +73,34 @@ class ClimberTest < Test::Unit::TestCase
   end
 
 
+  def test_enumerable_works_correctly
+    climber = StalkClimber::Climber.new(BEANSTALK_ADDRESSES)
+    test_jobs = {}
+    climber.connection_pool.connections.each do |connection|
+      test_jobs[connection.address] = []
+      5.times.to_a.map! do
+          test_jobs[connection.address] << StalkClimber::Job.new(connection.transmit(StalkClimber::Connection::PROBE_TRANSMISSION))
+      end
+    end
+
+    assert_nothing_raised do
+      # verify enumeration can be short circuited
+      climber.any? do |job|
+        true
+      end
+
+      # test normal enumeration
+      climber.all? do |job|
+        job
+      end
+    end
+
+    climber.connection_pool.connections.each do |connection|
+      test_jobs[connection.address].map(&:delete)
+    end
+  end
+
+
   def test_each_is_an_alias_for_climb
     assert_equal(
       StalkClimber::Climber.instance_method(:climb),
@@ -53,6 +110,29 @@ class ClimberTest < Test::Unit::TestCase
   end
 
 
+  def test_each_threaded_is_an_alias_for_climb_threaded
+    assert_equal(
+      StalkClimber::Climber.instance_method(:climb_threaded),
+      StalkClimber::Climber.instance_method(:each_threaded),
+      'Expected StalkClimber::Climber#each_threaded to be an alias for StalkClimber::Climber#climb_threaded'
+    )
+  end
+
+
+  def test_max_job_ids_returns_the_correct_max_job_ids
+    climber = StalkClimber::Climber.new(BEANSTALK_ADDRESSES, 'test_tube')
+    max_ids = climber.max_job_ids
+    max_ids.each do |connection, max_id|
+      assert_equal connection.max_job_id - 1, max_id
+    end
+  end
+
+
+  def test_to_enum_returns_an_enumerator
+    assert_kind_of Enumerator, StalkClimber::Climber.new(BEANSTALK_ADDRESSES).to_enum
+  end
+
+
   def test_with_a_test_tube
     climber = StalkClimber::Climber.new(BEANSTALK_ADDRESSES, 'test_tube')
     assert_equal 'test_tube', climber.test_tube

data/test/unit/connection_test.rb

@@ -34,6 +34,19 @@ class ConnectionTest < Test::Unit::TestCase
   end
 
 
+  def test_deleted_jobs_should_not_be_enumerated
+    seeds = seed_jobs
+    seeds.map(&:delete)
+    seed_ids = seeds.map(&:id)
+
+    deleted = @connection.detect do |job|
+      seed_ids.include?(job.id)
+    end
+
+    assert_nil deleted, "Deleted job found in enumeration: #{deleted}"
+  end
+
+
   def test_each_caches_jobs_for_later_use
     seeds = seed_jobs
 
@@ -113,12 +126,62 @@ class ConnectionTest < Test::Unit::TestCase
   end
 
 
-  def test_each_calls_climb
-    @connection.expects(:climb)
+  def test_each_calls_to_enum
+    @connection.expects(:to_enum).returns(Enumerator.new { |yielder| yielder << 1 })
     @connection.each {}
   end
 
 
+  def test_fetch_job_returns_nil_or_the_requested_job_if_it_exists
+    assert_nothing_raised do
+      job = @connection.fetch_job(@connection.max_job_id)
+      assert_equal nil, job
+    end
+
+    probe = seed_jobs(1).first
+    assert_equal probe.id, @connection.fetch_job(probe.id).id
+    probe.delete
+  end
+
+
+  def test_fetch_job_bang_returns_requested_job_or_raises_an_error_if_job_does_not_exist
+    assert_raise Beaneater::NotFoundError do
+      @connection.fetch_job!(@connection.max_job_id)
+    end
+
+    probe = seed_jobs(1).first
+    assert_equal probe.id, @connection.fetch_job!(probe.id).id
+    probe.delete
+  end
+
+
+  def test_fetch_jobs_returns_each_requested_job_or_nil
+    assert_nothing_raised do
+      jobs = @connection.fetch_jobs(@connection.max_job_id, @connection.max_job_id)
+      assert_equal [nil, nil], jobs
+    end
+
+    probes = seed_jobs(2)
+    probe_ids = probes.map(&:id)
+    assert_equal probe_ids, @connection.fetch_jobs(probe_ids).map(&:id)
+    probes.map(&:delete)
+  end
+
+
+  def test_fetch_jobs_bang_returns_requested_jobs_or_raises_an_error_if_any_job_does_not_exist
+    probes = seed_jobs(2)
+
+    probe_ids = probes.map(&:id)
+    assert_equal probe_ids, @connection.fetch_jobs!(probe_ids).map(&:id)
+
+    assert_raise Beaneater::NotFoundError do
+      @connection.fetch_jobs!(probe_ids.first, @connection.max_job_id, probe_ids.last)
+    end
+
+    probes.map(&:delete)
+  end
+
+
   def test_max_job_id_returns_expected_max_job_id
     initial_max = @connection.max_job_id
     seed_jobs(3).map(&:delete)
@@ -181,28 +244,8 @@ class ConnectionTest < Test::Unit::TestCase
   end
 
 
-  def test_with_job_yields_nil_or_the_requested_job_if_it_exists
-    assert_nothing_raised do
-      @connection.with_job(@connection.max_job_id) do |job|
-        assert_equal nil, job
-      end
-    end
-
-    probe = seed_jobs(1).first
-    @connection.with_job(probe.id) do |job|
-      assert_equal probe.id, job.id
-    end
-    probe.delete
-  end
-
-
-  def test_with_job_bang_does_not_execute_block_and_raises_error_if_job_does_not_exist
-    block = lambda {}
-    block.expects(:call).never
-    assert_raise Beaneater::NotFoundError do
-      Object.any_instance.expects(:yield).never
-      @connection.with_job!(@connection.max_job_id, &block)
-    end
+  def test_to_enum_returns_an_enumerator
+    assert_kind_of Enumerator, @connection.to_enum
   end
 
 end

data/test/unit/job_test.rb

@@ -9,11 +9,11 @@ class Job < Test::Unit::TestCase
   end
 
 
-  def test_body_retrives_performs_peek_and_parses_json
-    body = {'test' => true}
+  def test_body_performs_peek_and_parses_json
+    body = {'test' => true}.to_json
 
     @job.connection.expects(:transmit).returns({
-      :body => body.to_json,
+      :body => body,
     })
     assert_equal body, @job.body
 
@@ -53,7 +53,7 @@ class Job < Test::Unit::TestCase
     assert_equal @connection, job.connection
     assert_equal @job.id, job.id
     assert_equal 'FOUND', job.instance_variable_get(:@status)
-    assert_equal({}, job.body)
+    assert_equal('{}', job.body)
     refute job.instance_variable_get(:@stats)
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stalk_climber
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-04 00:00:00.000000000 Z
+date: 2013-11-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -117,3 +117,4 @@ test_files:
 - test/unit/connection_pool_test.rb
 - test/unit/connection_test.rb
 - test/unit/job_test.rb
+has_rdoc: