deferred_job 0.0.1

data/README.md

@@ -0,0 +1,103 @@
+# DeferredJob
+
+DeferredJob is a small library meant to work with Resque that allows you to add
+a set of pre-conditions that must be met before a Resque job kicks off.
+
+## Usage
+
+### Creating a DeferredJob
+
+To create a deferred job, you must give it an id, and the name/arguments
+of a worker to kick off when the preconditions are met:
+
+``` ruby
+job = Resque::DeferredJob.create id, SomeWorker, 'worker', 'args'
+```
+
+_NOTE:_ If you try to re-create an existing job, you'll clear it out.
+
+### Adding preconditions
+
+To add preconditions, you can use `#wait_for`.  So if you wanted to wait until
+a few things are done, you can add them one at a time, or in bulk:
+
+``` ruby
+job.wait_for 'import-1-data'
+job.wait_for 'import-2-data'
+job.wait_for 'import-1-photos', 'import-2-photos'
+```
+
+### Checking preconditions
+
+At any time before a job executes, you can check out its preconditions with
+a few inspection methods:
+
+``` ruby
+# See if we are waiting for a specific thing
+job.waiting_for?('import-1-data') # true
+
+# See what things we are waiting for
+job.waiting_for # 'import-1-data', 'import-2-data', ...
+
+# Count the number of things we're waiting for
+job.count # 4
+
+# See if we're waiting on anything at all
+job.empty? # false
+```
+
+### Finishing preconditions
+
+As you finish the preconditions, the same way you added them with `#wait_for`,
+you remove them with `#done`.  When the set is empty, the job will kick
+off with the args you specified in the initializer.  You don't need
+to finish things in the same order you put them in (and hopefully you
+aren't):
+
+``` ruby
+job.done 'import-1-data'
+job.done 'import-1-photos', 'import-2-photos'
+job.done 'import-2-data' # job kick off!
+```
+
+### Loading an existing job
+
+Most times, you'll have the need to use a `DeferredJob` in multiple
+pieces of your code that don't see each other (ie: inside of your workers).
+In that case, load a previous job like so:
+
+``` ruby
+# Check existence if you'd like
+Resque::DeferredJob.exists? id # true
+
+# Load the job up
+job = Resque::DeferredJob.find id
+```
+
+_NOTE:_ If you try to find a job that does not exist, you'll raise an
+exception (`Resque::NoSuchKey`).
+
+## Advanced
+
+### Redis Client
+
+By default, `DeferredJob` will use the same redis instance as Resque.
+If you'd like to change that, you can set the redis instace like so:
+
+``` ruby
+Resque::DeferredJob.redis = your_instace
+```
+
+### Key Generation
+
+By default, `DeferredJob` will generate redis keys that look
+like `deferred-job:#{id}`.  It can be useful to change that, so you can
+specify a new lambda expression for generating the keys:
+
+``` ruby
+Resque::DeferredJob.key_lambda = lambda { |id| "job:#{id}" }
+```
+
+## License
+
+Distributed under the MIT License.  See the attached LICENSE file.

data/lib/deferred_job.rb

@@ -0,0 +1,185 @@
+require 'bundler/setup'
+require 'resque'
+
+begin
+  require 'active_support/core_ext/string/inflections'
+rescue LoadError
+  require 'active_support'
+end
+
+module Resque
+
+  class NoSuchKey < StandardError
+  end
+
+  class DeferredJob
+
+    include Helpers
+
+    attr_accessor :verbose
+    attr_reader :id, :klass, :args, :set_key
+
+    # Initialize a new DeferredJob
+    # @param [String] id - The ID of the job
+    # @param [Class, String] klass - The class to run
+    # @param [Array] args - The arguments for the job
+    def initialize(id, klass, *args)
+      @id = id
+      @set_key = self.class.key_for id
+      @klass = klass.is_a?(String) ? klass.constantize : klass
+      @args = args
+    end
+
+    # Clear all entries in the set
+    def clear
+      redis.del @set_key
+    end
+
+    # Clear and then remove the key for this job
+    def destroy
+      redis.del @set_key
+      redis.del @id
+    end
+
+    # Determine if the set is empty
+    # @return [Boolean] whether or not the set is empty
+    def empty?
+      count == 0
+    end
+
+    # Count the number of elements in the set
+    # @return [Fixnum] the count of the elements in the set
+    def count
+      redis.scard(@set_key).to_i
+    end
+
+    # Wait for a thing before continuing
+    # @param [Array] things - The things to add
+    # @return [Fixnum] the number of things added
+    # NOTE >= 2.4 should use sadd with multiple things
+    def wait_for(*things)
+      things.each do |thing|
+        log "DeferredJob #{@id} will wait for #{thing.inspect}"
+        redis.sadd @set_key, thing
+      end
+    end
+
+    def waiting_for?(thing)
+      redis.sismember(@set_key, thing)
+    end
+
+    def waiting_for
+      redis.smembers(@set_key)
+    end
+
+    # Mark a thing as finished
+    # @param [Array] things - The things to remove
+    # @return [Fixnum] the number of things removed
+    # NOTE >= 2.4 should use srem with multiple things
+    def done(*things)
+      results = redis.multi do
+        redis.scard @set_key
+        things.each do |thing|
+          log "DeferredJob #{id} done with #{thing.inspect}"
+          redis.srem @set_key, thing
+        end
+        redis.scard @set_key
+      end
+      if results.first > 0
+        if results.last.zero?
+          log "DeferredJob #{id} all conditions met; will now self-destruct"
+          begin
+            execute
+          ensure
+            destroy
+          end
+        else
+          log "DeferredJob #{id} waiting on #{results.last} conditions"
+        end
+      end
+    end
+
+   # Don't allow new instances
+    private_class_method :new
+
+    private
+
+    # A helper (similar to Resque::Helpers)
+    def redis
+      self.class.redis
+    end
+
+    # How to log - mirrors a pattern in resque
+    def log(msg)
+      if verbose
+        if defined?(Rails)
+          Rails.logger.debug(msg)
+        else
+          puts msg
+        end
+      end
+    end
+
+    # Execute the job with resque
+    def execute
+      Resque.enqueue klass, *args
+    end
+
+    class << self
+
+      attr_writer :redis, :key_lambda
+
+      # The way we turn id into set_key
+      # @param [Object] id - the id of the job
+      # @return [String] - the set_key to use for the given id
+      def key_for(id)
+        lamb = @key_lambda || lambda { |id| "deferred-job:#{id}" }
+        lamb.call id
+      end
+
+      # Create a new DeferredJob
+      # @param [Object] id - the id of the job
+      # @param [Class, String] klass - The class of the job to run
+      # @param [Array] args - The args to send to the job
+      # @return [Resque::DeferredJob] - the job, cleared
+      def create(id, klass, *args)
+        plan = [klass.to_s, args]
+        redis.set(id, MultiJson.encode(plan))
+        # Return the job
+        job = new(id, klass, *args)
+        job.clear
+        job
+      end
+
+      # Find an existing DeferredJob
+      # @param [Object] id - the id of the job
+      # @return [Resque::DeferredJob] - the job
+      def find(id)
+        plan_data = redis.get(id)
+        # If found, return the job, otherwise raise NoSuchKey
+        if plan_data.nil?
+          raise ::Resque::NoSuchKey.new "No Such DeferredJob: #{id}"
+        else
+          plan = MultiJson.decode(plan_data)
+          new(id, plan.first, *plan.last)
+        end
+      end
+
+      # Determine if a give job exists
+      # @param [Object] id - the id of the job to lookup
+      # @return [Boolean] - whether or not the job exists
+      def exists?(id)
+        !redis.get(id).nil?
+      end
+
+      # Our own redis instance in case people want to separate from resque
+      # @return [Redis::Client] - a redis client
+      def redis
+        @redis || Resque.redis
+      end
+
+    end
+
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require 'simplecov'
+SimpleCov.start
+
+require_relative '../lib/deferred_job'
+
+class SomethingWorker
+  @queue = :high
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: deferred_job
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- John Crepezzi
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: multi_json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: resque
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Resque Deferred Jobs
+email: john@brewster.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/deferred_job.rb
+- README.md
+- spec/spec_helper.rb
+homepage: http://github.com/brewster/deferred_job
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Resque Deferred Job Library
+test_files:
+- spec/spec_helper.rb
+has_rdoc: