stalk_climber 0.0.6 → 0.1.0

data/.rdoc_options

@@ -0,0 +1,7 @@
+--- !ruby/object:RDoc::Options
+encoding: UTF-8
+static_path: []
+rdoc_include:
+- .
+charset: UTF-8
+exclude: !ruby/regexp /(?:test)/

data/.travis.yml

@@ -4,17 +4,15 @@ rvm:
   - 1.9.3
   - 2.0.0
   - jruby-19mode
-  - rbx-2.0.0
+  - rbx
 
 before_install:
-  - sudo apt-get update -qq
-  - sudo apt-get install -qq beanstalkd
-  - sudo sed -i 's/#START=yes/START=yes/' /etc/default/beanstalkd
-  - sudo service beanstalkd start
-  - cat /etc/init.d/beanstalkd | sed 's/NAME=beanstalkd/NAME=beanstalkd2/' | sudo tee /etc/init.d/beanstalkd2 2>&1>/dev/null
-  - cat /etc/default/beanstalkd | sed 's/11300/11301/' | sudo tee /etc/default/beanstalkd2 2>&1>/dev/null
-  - sudo chmod +x /etc/init.d/beanstalkd2
-  - sudo service beanstalkd2 start
+  - curl -L https://github.com/kr/beanstalkd/archive/v1.9.tar.gz | tar xz -C /tmp
+  - cd /tmp/beanstalkd-1.9/
+  - make
+  - ./beanstalkd &
+  - ./beanstalkd -p 11301 &
+  - cd $TRAVIS_BUILD_DIR
 
 env:
   - BEANSTALK_ADDRESSES='beanstalk://localhost:11300,beanstalk://localhost:11301'
@@ -22,4 +20,4 @@ env:
 matrix:
   allow_failures:
     - rvm: jruby-19mode
-    - rvm: rbx-2.0.0
+    - rvm: rbx

data/Gemfile

@@ -7,4 +7,5 @@ gem 'debugger', :group => [:development, :test], :platforms => [:mri]
 group :test do
   gem 'coveralls', :require => false
   gem 'mocha', :require => false
+  gem 'minitest_should'
 end

data/lib/stalk_climber.rb

@@ -1,9 +1,14 @@
 module StalkClimber; end
 
+require 'forwardable'
 require 'beaneater'
 require 'stalk_climber/version'
 require 'stalk_climber/lazy_enumerable'
+require 'stalk_climber/climber_enumerable'
+require 'stalk_climber/climber_enumerables'
 require 'stalk_climber/connection'
 require 'stalk_climber/connection_pool'
 require 'stalk_climber/climber'
 require 'stalk_climber/job'
+require 'stalk_climber/tubes'
+require 'stalk_climber/tube'

data/lib/stalk_climber/climber.rb

@@ -1,11 +1,24 @@
 module StalkClimber
   class Climber
-    include RUBY_VERSION >= '2.0.0' ? LazyEnumerable : Enumerable
 
-    attr_accessor :beanstalk_addresses, :test_tube
-    attr_reader :cache
+    extend Forwardable
 
-    # Returns or creates a ConnectionPool from beanstalk_addresses
+    def_delegator :connection_pool, :tubes
+
+    # Collection of beanstalk_addresses the pool is connected to
+    attr_accessor :beanstalk_addresses
+
+    # Accessor to the climber's Jobs instance
+    attr_reader :jobs
+
+    # Tube used when injecting jobs to probe state of Beanstalkd
+    attr_accessor :test_tube
+
+    # :call-seq:
+    #   connection_pool() => StalkClimber::ConnectionPool
+    #
+    # Returns or creates a ConnectionPool from beanstalk_addresses. Raises a
+    # RuntimeError if #beanstalk_addresses has not been set.
     def connection_pool
       return @connection_pool unless @connection_pool.nil?
       if self.beanstalk_addresses.nil?
@@ -15,50 +28,27 @@ 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 => e
-          return (e.nil? || !e.respond_to?(:result) || e.result.nil?) ? nil : e.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_threaded(&block)
-      threads = []
-      self.connection_pool.connections.each do |connection|
-        threads << Thread.new { connection.each(&block) }
-      end
-      threads.each(&:join)
-      return
-    end
-    alias_method :each_threaded, :climb_threaded
-
-
-    # Creates a new Climber instance, optionally yielding the instance
-    # if a block is given
-    def initialize(beanstalk_addresses = nil, test_tube = nil)
+    # Creates a new Climber instance, optionally yielding the instance for
+    # configuration if a block is given
+    #
+    #   Climber.new('beanstalk://localhost:11300', 'stalk_climber')
+    #     #=> #<StalkClimber::Job beanstalk_addresses="beanstalk://localhost:11300" test_tube="stalk_climber">
+    def initialize(beanstalk_addresses = nil, test_tube = nil) # :yields: climber
       self.beanstalk_addresses = beanstalk_addresses
       self.test_tube = test_tube
+      @jobs = StalkClimber::Jobs.new(self)
       yield(self) if block_given?
     end
 
 
-    # Returns a hash with connections as keys and max_job_ids as values
+    # :call-seq:
+    #   max_job_ids() => Hash{Beaneater::Connection => Integer}
+    #
+    # Returns a Hash with connections as keys and max_job_ids as values
+    #
+    #   climber = Climber.new('beanstalk://localhost:11300', 'stalk_climber')
+    #   climber.max_job_ids
+    #     #=> {#<Beaneater::Connection host="localhost" port=11300>=>1183}
     def max_job_ids
       connection_pairs = connection_pool.connections.map do |connection|
         [connection, connection.max_job_id]
@@ -67,19 +57,17 @@ module StalkClimber
     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
+    # :call-seq:
+    #   to_s() => String
+    #
+    # Return string representation of climber
+    #
+    #   Climber.new('beanstalk://localhost:11300', 'stalk_climber').to_s
+    #     #=> #<StalkClimber::Job beanstalk_addresses="beanstalk://localhost:11300" test_tube="stalk_climber">
+    def to_s
+      return "#<StalkClimber::Job beanstalk_addresses=#{beanstalk_addresses.inspect} test_tube=#{test_tube.inspect}>"
     end
+    alias :inspect :to_s
 
   end
 end

data/lib/stalk_climber/climber_enumerable.rb

@@ -0,0 +1,110 @@
+module StalkClimber
+
+  module ClimberEnumerable
+
+    include RUBY_VERSION >= '2.0.0' ? LazyEnumerable : Enumerable
+    extend Forwardable
+
+    def_delegators :to_enum, :each
+
+    # A reference to the climber instance to which this enumerable belongs
+    attr_reader :climber
+
+
+    # :call-seq:
+    #   new(enumerator_method) => New class including ClimberEnumerable
+    #
+    # Factory that simplifies the creation of ClimberEnumerable classes.
+    # Otherwise in simple cases a class would have to be defined only to
+    # include this module and set the desired :enumerator_method symbol.
+    # The :enumerator_method parameter is passed to each connection in
+    # the connection pool of the climber given at instantiation.
+    #
+    #   jobs = ClimberEnumerable.new(:each_job)
+    #   instance = jobs.new(climber)
+    #   instance.each do |job|
+    #     break job
+    #   end
+    #     #=> #<StalkClimber::Job id=1 body="Work to be done">
+    #
+    def self.new(enumerator_method)
+      return Class.new do
+        include StalkClimber::ClimberEnumerable
+        @enumerator_method = enumerator_method
+
+        # Create a new instance of a ClimberEnumerable when given +climber+ that
+        # references the StalkClimber that owns it
+        def initialize(climber)
+          @climber = climber
+        end
+      end
+    end
+
+
+    # Add :enumerator_method class level accessor to inheriting class
+    def self.included(base) # :nodoc:
+      class << base
+        attr_reader :enumerator_method
+      end
+    end
+
+
+    # Perform a threaded iteration across all connections in the climber's
+    # connection pool. This method cannot be used for enumerable enumeration
+    # because a break called within 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 elements.
+    # An instance of the element is yielded with each iteration.
+    #
+    #   jobs = ClimberEnumerable.new(:each_job)
+    #   instance = jobs.new(climber)
+    #   instance.each_threaded do |job|
+    #     ...
+    #   end
+    def each_threaded(&block) # :yields: Object
+      threads = []
+      climber.connection_pool.connections.each do |connection|
+        threads << Thread.new { connection.send(self.class.enumerator_method, &block) }
+      end
+      threads.each(&:join)
+      return
+    end
+
+
+    # :call-seq:
+    #   to_enum() => Enumerator
+    #
+    # Returns an Enumerator for enumerating elements on all connections.
+    # Connections are enumerated in the order defined. See Connection#to_enum
+    # for more information
+    # An instance of the element is yielded with each iteration.
+    def to_enum
+      return Enumerator.new do |yielder|
+        climber.connection_pool.connections.each do |connection|
+          connection.send(self.class.enumerator_method) do |element|
+            yielder << element
+          end
+        end
+      end
+    end
+
+
+    # :call-seq:
+    #   each {|obj| block} => Object
+    #
+    # Iterate over all elements on all connections in the climber's connection
+    # pool. If no block is given, returns the enumerator provided by #to_enum.
+    # An instance of the element is yielded to a given block. For more information
+    # see the method on Connection designated :enumerator_method by the implementing class
+    #
+    #   jobs = ClimberEnumerable.new(:each_job)
+    #   instance = jobs.new(climber)
+    #   instance.each do |job|
+    #     break job
+    #   end
+    #     #=> #<StalkClimber::Job id=1 body="Work to be done">
+
+  end
+
+end

data/lib/stalk_climber/climber_enumerables.rb

@@ -0,0 +1,7 @@
+module StalkClimber
+
+  # ClimberEnumerable for iterating over connection jobs. See ClimberEnumerable
+  # for more information
+  Jobs = StalkClimber::ClimberEnumerable.new(:each_job)
+
+end

data/lib/stalk_climber/connection.rb

@@ -1,48 +1,43 @@
 module StalkClimber
   class Connection < Beaneater::Connection
-    include RUBY_VERSION >= '2.0.0' ? LazyEnumerable : Enumerable
 
+    extend Forwardable
+
+    def_delegator :job_enumerator, :each, :each_job
+
+    # Default tube used when no custom tube in use
     DEFAULT_TUBE = 'stalk_climber'
+
+    # Transmission used to probe state of Beanstalkd. Created with lowest
+    # possible priority and delay to reduce possibility of interference.
     PROBE_TRANSMISSION = "put 4294967295 0 300 2\r\n{}"
 
-    attr_reader :max_climbed_job_id, :min_climbed_job_id, :test_tube
+    # Last known maximum job id on the Beanstalkd server
+    attr_reader :max_climbed_job_id
+    # Last known existing minimum job id on the Beanstalkd server
+    attr_reader :min_climbed_job_id
+    # Tube to use when probing the Beanstalkd server for information
+    attr_reader :test_tube
 
 
+    # :call-seq:
+    #   cached_jobs() => Hash
+    #
     # Returns or creates a Hash used for caching jobs by ID
-    def cache
-      return @cache ||= {}
+    def cached_jobs
+      return @cached_jobs ||= {}
     end
 
 
     # Resets the job cache and reinitializes the min and max climbed job ids
-    def clear_cache
-      @cache = nil
+    def clear_job_cache
+      @cached_jobs = nil
       @min_climbed_job_id = Float::INFINITY
       @max_climbed_job_id = 0
+      return true
     end
 
 
-    # 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 climb
-      enum = to_enum
-      return enum unless block_given?
-      loop do
-        begin
-          yield enum.next
-        rescue StopIteration => e
-          return (e.nil? || !e.respond_to?(:result) || e.result.nil?) ? nil : e.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)
@@ -84,7 +79,7 @@ module StalkClimber
     def initialize(address, test_tube = DEFAULT_TUBE)
       super(address)
       @test_tube = test_tube || DEFAULT_TUBE
-      clear_cache
+      clear_job_cache
       yield(self) if block_given?
       use_test_tube
     end
@@ -92,7 +87,7 @@ module StalkClimber
 
     # Determintes the max job ID of the connection by inserting a job into the test tube
     # and immediately deleting it. Before returning the max ID, the max ID is used to
-    # update the max_climbed_job_id (if sequentual) and possibly invalidate the cache.
+    # update the max_climbed_job_id (if sequentual) and possibly invalidate the job cache.
     # The cache will be invalidated if the max ID is less than any known IDs since
     # new job IDs should always increment unless there's been a change in server state.
     def max_job_id
@@ -111,12 +106,12 @@ module StalkClimber
 
 
     # Returns an Enumerator for crawling all existing jobs for a connection.
-    # See Connection#each for more information.
-    def to_enum
+    # See Connection#each_job for more information.
+    def job_enumerator
       return Enumerator.new do |yielder|
         max_id = max_job_id
 
-        initial_cached_jobs = cache.values_at(*cache.keys.sort.reverse)
+        initial_cached_jobs = cached_jobs.values_at(*cached_jobs.keys.sort.reverse)
 
         max_id.downto(self.max_climbed_job_id + 1) do |job_id|
           job = fetch_and_cache_job(job_id)
@@ -127,7 +122,7 @@ module StalkClimber
           if job.exists?
             yielder << job
           else
-            self.cache.delete(job.id)
+            self.cached_jobs.delete(job.id)
           end
         end
 
@@ -135,6 +130,7 @@ module StalkClimber
           job = fetch_and_cache_job(job_id)
           yielder << job unless job.nil?
         end
+        nil
       end
     end
 
@@ -147,7 +143,7 @@ module StalkClimber
     # and nil is returned
     def fetch_and_cache_job(job_id)
       job = fetch_job(job_id)
-      self.cache[job_id] = job unless job.nil?
+      self.cached_jobs[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
@@ -155,13 +151,13 @@ module StalkClimber
 
 
     # Uses +new_max_id+ to update the max_climbed_job_id (if sequentual) and possibly invalidate
-    # the cache. The cache will be invalidated if +new_max_id+ is less than any known IDs since
-    # new job IDs should always increment unless there's been a change in server state.
+    # the job cache. The job cache will be invalidated if +new_max_id+ is less than any known
+    # IDs since new job IDs should always increment unless there's been a change in server state.
     def update_climbed_job_ids_from_max_id(new_max_id)
       if @max_climbed_job_id > 0 && @max_climbed_job_id == new_max_id - 1
         @max_climbed_job_id = new_max_id
       elsif new_max_id < @max_climbed_job_id
-        clear_cache
+        clear_job_cache
       end
     end
 
@@ -178,5 +174,21 @@ module StalkClimber
       end
     end
 
+
+    # :call-seq:
+    #   each_job() => Enumerator
+    #   each_job {|job| 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 job cache. Finally, jobs between min_climbed_job_id and 1 are pulled from beanstalk,
+    # cached, and yielded.
+    #
+    #   connection = Connection.new('localhost:11300')
+    #   connection.each_job do |job|
+    #     job.delete
+    #   end
+
   end
 end