dburkes-delayed_job 1.7.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2005 Tobias Luetke
+
+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 PURPOa AND
+NONINFRINGEMENT. IN NO EVENT SaALL 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,111 @@
+h1. Delayed::Job
+
+Delated_job (or DJ) encapsulates the common pattern of asynchronously executing longer tasks in the background. 
+
+It is a direct extraction from Shopify where the job table is responsible for a multitude of core tasks. Amongst those tasks are:
+
+* sending massive newsletters
+* image resizing
+* http downloads
+* updating smart collections
+* updating solr, our search server, after product changes
+* batch imports 
+* spam checks 
+            
+h2. Setup
+            
+The library evolves around a delayed_jobs table which looks as follows: 
+
+  create_table :delayed_jobs, :force => true do |table|
+    table.integer  :priority, :default => 0      # Allows some jobs to jump to the front of the queue
+    table.integer  :attempts, :default => 0      # Provides for retries, but still fail eventually.
+    table.text     :handler                      # YAML-encoded string of the object that will do work
+    table.string   :last_error                   # reason for last failure (See Note below)
+    table.datetime :run_at                       # When to run. Could be Time.now for immediately, or sometime in the future.
+    table.datetime :locked_at                    # Set when a client is working on this object
+    table.datetime :failed_at                    # Set when all retries have failed (actually, by default, the record is deleted instead)
+    table.string   :locked_by                    # Who is working on this object (if locked)
+    table.timestamps
+  end
+
+On failure, the job is scheduled again in 5 seconds + N ** 4, where N is the number of retries.
+
+The default MAX_ATTEMPTS is 25- jobs can override this value by responding to :max_attempts. After this, the job 
+either deleted (default), or left in the database with "failed_at" set. With the default of 25 attempts, the last 
+retry will be 20 days later, with the last interval being almost 100 hours.
+
+The default MAX_RUN_TIME is 4.hours. If your job takes longer than that, another computer could pick it up. It's up to you to
+make sure your job doesn't exceed this time. You should set this to the longest time you think the job could take.
+
+By default, it will delete failed jobs (and it always deletes successful jobs). If you want to keep failed jobs, set
+Delayed::Job.destroy_failed_jobs = false. The failed jobs will be marked with non-null failed_at.
+
+Here is an example of changing job parameters in Rails:
+
+  # config/initializers/delayed_job_config.rb
+  Delayed::Job.destroy_failed_jobs = false
+  silence_warnings do
+    Delayed::Job.const_set("MAX_ATTEMPTS", 3)
+    Delayed::Job.const_set("MAX_RUN_TIME", 5.minutes)
+  end
+
+Note: If your error messages are long, consider changing last_error field to a :text instead of a :string (255 character limit).
+
+
+h2. Usage
+
+Jobs are simple ruby objects with a method called perform. Any object which responds to perform can be stuffed into the jobs table.
+Job objects are serialized to yaml so that they can later be resurrected by the job runner. 
+
+  class NewsletterJob < Struct.new(:text, :emails)
+    def perform
+      emails.each { |e| NewsletterMailer.deliver_text_to_email(text, e) }
+    end    
+  end  
+  
+  Delayed::Job.enqueue NewsletterJob.new('lorem ipsum...', Customers.find(:all).collect(&:email))
+           
+There is also a second way to get jobs in the queue: send_later. 
+
+  
+  BatchImporter.new(Shop.find(1)).send_later(:import_massive_csv, massive_csv)                                                    
+  
+
+This will simply create a Delayed::PerformableMethod job in the jobs table which serializes all the parameters you pass to it. There are some special smarts for active record objects
+which are stored as their text representation and loaded from the database fresh when the job is actually run later.
+                                                                                                                              
+                                                                                                                    
+h2. Running the jobs
+
+You can invoke @rake jobs:work@ which will start working off jobs. You can cancel the rake task with @CTRL-C@. 
+
+You can also run by writing a simple @script/job_runner@, and invoking it externally:
+  
+<pre><code>
+  #!/usr/bin/env ruby
+  require File.dirname(__FILE__) + '/../config/environment'
+  
+  Delayed::Worker.new.start  
+</code></pre>
+
+Workers can be running on any computer, as long as they have access to the database and their clock is in sync. You can even
+run multiple workers on per computer, but you must give each one a unique name. (TODO: put in an example)
+Keep in mind that each worker will check the database at least every 5 seconds.
+
+Note: The rake task will exit if the database has any network connectivity problems.
+
+h3. Cleaning up
+
+You can invoke @rake jobs:clear@ to delete all jobs in the queue.
+
+h3. Changes
+
+* 1.7.0: Added failed_at column which can optionally be set after a certain amount of failed job attempts. By default failed job attempts are destroyed after about a month. 
+
+* 1.6.0: Renamed locked_until to locked_at. We now store when we start a given job instead of how long it will be locked by the worker. This allows us to get a reading on how long a job took to execute.                    
+
+* 1.5.0: Job runners can now be run in parallel. Two new database columns are needed: locked_until and locked_by. This allows us to use   pessimistic locking instead of relying on row level locks. This enables us to run as many worker processes as we need to speed up queue processing.
+
+* 1.2.0: Added #send_later to Object for simpler job creation
+
+* 1.0.0: Initial release

data/delayed_job.gemspec

@@ -0,0 +1,41 @@
+#version = File.read('README.textile').scan(/^\*\s+([\d\.]+)/).flatten
+
+Gem::Specification.new do |s|
+  s.name     = "delayed_job"
+  s.version  = "1.7.0"
+  s.date     = "2008-11-28"
+  s.summary  = "Database-backed asynchronous priority queue system -- Extracted from Shopify"
+  s.email    = "tobi@leetsoft.com"
+  s.homepage = "http://github.com/tobi/delayed_job/tree/master"
+  s.description = "Delated_job (or DJ) encapsulates the common pattern of asynchronously executing longer tasks in the background. It is a direct extraction from Shopify where the job table is responsible for a multitude of core tasks."
+  s.authors  = ["Tobias Lütke"]
+
+  # s.bindir = "bin"
+  # s.executables = ["delayed_job"]
+  # s.default_executable = "delayed_job"
+
+  s.has_rdoc = false
+  s.rdoc_options = ["--main", "README.textile"]
+  s.extra_rdoc_files = ["README.textile"]
+
+  # run git ls-files to get an updated list
+  s.files = %w[
+    MIT-LICENSE
+    README.textile
+    delayed_job.gemspec
+    init.rb
+    lib/delayed/job.rb
+    lib/delayed/message_sending.rb
+    lib/delayed/performable_method.rb
+    lib/delayed/worker.rb
+    lib/delayed_job.rb
+    tasks/jobs.rake
+    tasks/tasks.rb
+  ]
+  s.test_files = %w[
+    spec/database.rb
+    spec/delayed_method_spec.rb
+    spec/job_spec.rb
+    spec/story_spec.rb
+  ]
+end

data/init.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + '/lib/delayed_job'

data/lib/delayed/job.rb

@@ -0,0 +1,272 @@
+module Delayed
+
+  class DeserializationError < StandardError
+  end
+
+  # A job object that is persisted to the database.
+  # Contains the work object as a YAML field.
+  class Job < ActiveRecord::Base
+    MAX_ATTEMPTS = 25
+    MAX_RUN_TIME = 4.hours
+    set_table_name :delayed_jobs
+
+    # By default failed jobs are destroyed after too many attempts.
+    # If you want to keep them around (perhaps to inspect the reason
+    # for the failure), set this to false.
+    cattr_accessor :destroy_failed_jobs
+    self.destroy_failed_jobs = true
+
+    # Every worker has a unique name which by default is the pid of the process.
+    # There are some advantages to overriding this with something which survives worker retarts:
+    # Workers can safely resume working on tasks which are locked by themselves. The worker will assume that it crashed before.
+    cattr_accessor :worker_name
+    self.worker_name = "host:#{Socket.gethostname} pid:#{Process.pid}" rescue "pid:#{Process.pid}"
+
+    NextTaskSQL         = '(run_at <= ? AND (locked_at IS NULL OR locked_at < ?) OR (locked_by = ?)) AND failed_at IS NULL'
+    NextTaskOrder       = 'priority DESC, run_at ASC'
+
+    ParseObjectFromYaml = /\!ruby\/\w+\:([^\s]+)/
+
+    cattr_accessor :min_priority, :max_priority
+    self.min_priority = nil
+    self.max_priority = nil
+
+    # When a worker is exiting, make sure we don't have any locked jobs.
+    def self.clear_locks!
+      update_all("locked_by = null, locked_at = null", ["locked_by = ?", worker_name])
+    end
+
+    def failed?
+      failed_at
+    end
+    alias_method :failed, :failed?
+
+    def payload_object
+      @payload_object ||= deserialize(self['handler'])
+    end
+
+    def name
+      @name ||= begin
+        payload = payload_object
+        if payload.respond_to?(:display_name)
+          payload.display_name
+        else
+          payload.class.name
+        end
+      end
+    end
+
+    def payload_object=(object)
+      self['handler'] = object.to_yaml
+    end
+
+    # Reschedule the job in the future (when a job fails).
+    # Uses an exponential scale depending on the number of failed attempts.
+    def reschedule(message, backtrace = [], time = nil)
+      if self.attempts < (payload_object.send(:max_attempts) rescue MAX_ATTEMPTS)
+        time ||= Job.db_time_now + (attempts ** 4) + 5
+
+        self.attempts    += 1
+        self.run_at       = time
+        self.last_error   = message + "\n" + backtrace.join("\n")
+        self.unlock
+        save!
+      else
+        logger.info "* [JOB] PERMANENTLY removing #{self.name} because of #{attempts} consequetive failures."
+        destroy_failed_jobs ? destroy : update_attribute(:failed_at, Time.now)
+      end
+    end
+
+
+    # Try to run one job. Returns true/false (work done/work failed) or nil if job can't be locked.
+    def run_with_lock(max_run_time, worker_name)
+      logger.info "* [JOB] aquiring lock on #{name}"
+      unless lock_exclusively!(max_run_time, worker_name)
+        # We did not get the lock, some other worker process must have
+        logger.warn "* [JOB] failed to aquire exclusive lock for #{name}"
+        return nil # no work done
+      end
+
+      begin
+        runtime =  Benchmark.realtime do
+          invoke_job # TODO: raise error if takes longer than max_run_time
+          destroy
+        end
+        # TODO: warn if runtime > max_run_time ?
+        logger.info "* [JOB] #{name} completed after %.4f" % runtime
+        return true  # did work
+      rescue Exception => e
+        reschedule e.message, e.backtrace
+        log_exception(e)
+        return false  # work failed
+      end
+    end
+
+    # Add a job to the queue
+    def self.enqueue(*args, &block)
+      object = block_given? ? EvaledJob.new(&block) : args.shift
+
+      unless object.respond_to?(:perform) || block_given?
+        raise ArgumentError, 'Cannot enqueue items which do not respond to perform'
+      end
+    
+      priority = args.first || 0
+      run_at   = args[1]
+
+      Job.create(:payload_object => object, :priority => priority.to_i, :run_at => run_at)
+    end
+
+    # Find a few candidate jobs to run (in case some immediately get locked by others).
+    # Return in random order prevent everyone trying to do same head job at once.
+    def self.find_available(limit = 5, max_run_time = MAX_RUN_TIME)
+
+      time_now = db_time_now
+
+      sql = NextTaskSQL.dup
+
+      conditions = [time_now, time_now - max_run_time, worker_name]
+
+      if self.min_priority
+        sql << ' AND (priority >= ?)'
+        conditions << min_priority
+      end
+
+      if self.max_priority
+        sql << ' AND (priority <= ?)'
+        conditions << max_priority
+      end
+
+      conditions.unshift(sql)
+
+      records = ActiveRecord::Base.silence do
+        find(:all, :conditions => conditions, :order => NextTaskOrder, :limit => limit)
+      end
+
+      records.sort_by { rand() }
+    end
+
+    # Run the next job we can get an exclusive lock on.
+    # If no jobs are left we return nil
+    def self.reserve_and_run_one_job(max_run_time = MAX_RUN_TIME)
+
+      # We get up to 5 jobs from the db. In case we cannot get exclusive access to a job we try the next.
+      # this leads to a more even distribution of jobs across the worker processes
+      find_available(5, max_run_time).each do |job|
+        t = job.run_with_lock(max_run_time, worker_name)
+        return t unless t == nil  # return if we did work (good or bad)
+      end
+
+      nil # we didn't do any work, all 5 were not lockable
+    end
+
+    # Lock this job for this worker.
+    # Returns true if we have the lock, false otherwise.
+    def lock_exclusively!(max_run_time, worker = worker_name)
+      now = self.class.db_time_now
+      affected_rows = if locked_by != worker
+        # We don't own this job so we will update the locked_by name and the locked_at
+        self.class.update_all(["locked_at = ?, locked_by = ?", now, worker], ["id = ? and (locked_at is null or locked_at < ?)", id, (now - max_run_time.to_i)])
+      else
+        # We already own this job, this may happen if the job queue crashes.
+        # Simply resume and update the locked_at
+        self.class.update_all(["locked_at = ?", now], ["id = ? and locked_by = ?", id, worker])
+      end
+      if affected_rows == 1
+        self.locked_at    = now
+        self.locked_by    = worker
+        return true
+      else
+        return false
+      end
+    end
+
+    # Unlock this job (note: not saved to DB)
+    def unlock
+      self.locked_at    = nil
+      self.locked_by    = nil
+    end
+
+    # This is a good hook if you need to report job processing errors in additional or different ways
+    def log_exception(error)
+      logger.error "* [JOB] #{name} failed with #{error.class.name}: #{error.message} - #{attempts} failed attempts"
+      logger.error(error)
+    end
+
+    # Do num jobs and return stats on success/failure.
+    # Exit early if interrupted.
+    def self.work_off(num = 100)
+      success, failure = 0, 0
+
+      num.times do
+        case self.reserve_and_run_one_job
+        when true
+            success += 1
+        when false
+            failure += 1
+        else
+          break  # leave if no work could be done
+        end
+        break if $exit # leave if we're exiting
+      end
+
+      return [success, failure]
+    end
+
+    # Moved into its own method so that new_relic can trace it.
+    def invoke_job
+      payload_object.perform
+    end
+
+  private
+
+    def deserialize(source)
+      handler = YAML.load(source) rescue nil
+
+      unless handler.respond_to?(:perform)
+        if handler.nil? && source =~ ParseObjectFromYaml
+          handler_class = $1
+        end
+        attempt_to_load(handler_class || handler.class)
+        handler = YAML.load(source)
+      end
+
+      return handler if handler.respond_to?(:perform)
+
+      raise DeserializationError,
+        'Job failed to load: Unknown handler. Try to manually require the appropiate file.'
+    rescue TypeError, LoadError, NameError => e
+      raise DeserializationError,
+        "Job failed to load: #{e.message}. Try to manually require the required file."
+    end
+
+    # Constantize the object so that ActiveSupport can attempt
+    # its auto loading magic. Will raise LoadError if not successful.
+    def attempt_to_load(klass)
+       klass.constantize
+    end
+
+    # Get the current time (GMT or local depending on DB)
+    # Note: This does not ping the DB to get the time, so all your clients
+    # must have syncronized clocks.
+    def self.db_time_now
+      (ActiveRecord::Base.default_timezone == :utc) ? Time.now.utc : Time.now
+    end
+
+  protected
+
+    def before_save
+      self.run_at ||= self.class.db_time_now
+    end
+
+  end
+
+  class EvaledJob
+    def initialize
+      @job = yield
+    end
+
+    def perform
+      eval(@job)
+    end
+  end
+end

data/lib/delayed/message_sending.rb

@@ -0,0 +1,17 @@
+module Delayed
+  module MessageSending
+    def send_later(method, *args)
+      Delayed::Job.enqueue Delayed::PerformableMethod.new(self, method.to_sym, args)
+    end
+    
+    module ClassMethods
+      def handle_asynchronously(method)
+        without_name = "#{method}_without_send_later"
+        define_method("#{method}_with_send_later") do |*args|
+          send_later(without_name, *args)
+        end
+        alias_method_chain method, :send_later
+      end
+    end
+  end                               
+end

data/lib/delayed/performable_method.rb

@@ -0,0 +1,55 @@
+module Delayed
+  class PerformableMethod < Struct.new(:object, :method, :args)
+    CLASS_STRING_FORMAT = /^CLASS\:([A-Z][\w\:]+)$/
+    AR_STRING_FORMAT    = /^AR\:([A-Z][\w\:]+)\:(\d+)$/
+
+    def initialize(object, method, args)
+      raise NoMethodError, "undefined method `#{method}' for #{self.inspect}" unless object.respond_to?(method)
+
+      self.object = dump(object)
+      self.args   = args.map { |a| dump(a) }
+      self.method = method.to_sym
+    end
+    
+    def display_name  
+      case self.object
+      when CLASS_STRING_FORMAT then "#{$1}.#{method}"
+      when AR_STRING_FORMAT    then "#{$1}##{method}"
+      else "Unknown##{method}"
+      end      
+    end    
+
+    def perform
+      load(object).send(method, *args.map{|a| load(a)})
+    rescue ActiveRecord::RecordNotFound
+      # We cannot do anything about objects which were deleted in the meantime
+      true
+    end
+
+    private
+
+    def load(arg)
+      case arg
+      when CLASS_STRING_FORMAT then $1.constantize
+      when AR_STRING_FORMAT    then $1.constantize.find($2)
+      else arg
+      end
+    end
+
+    def dump(arg)
+      case arg
+      when Class              then class_to_string(arg)
+      when ActiveRecord::Base then ar_to_string(arg)
+      else arg
+      end
+    end
+
+    def ar_to_string(obj)
+      "AR:#{obj.class}:#{obj.id}"
+    end
+
+    def class_to_string(obj)
+      "CLASS:#{obj.name}"
+    end
+  end
+end

data/lib/delayed/worker.rb

@@ -0,0 +1,54 @@
+module Delayed
+  class Worker
+    SLEEP = 5
+
+    cattr_accessor :logger
+    self.logger = if defined?(Merb::Logger)
+      Merb.logger
+    elsif defined?(RAILS_DEFAULT_LOGGER)
+      RAILS_DEFAULT_LOGGER
+    end
+
+    def initialize(options={})
+      @quiet = options[:quiet]
+      Delayed::Job.min_priority = options[:min_priority] if options.has_key?(:min_priority)
+      Delayed::Job.max_priority = options[:max_priority] if options.has_key?(:max_priority)
+    end
+
+    def start
+      say "*** Starting job worker #{Delayed::Job.worker_name}"
+
+      trap('TERM') { say 'Exiting...'; $exit = true }
+      trap('INT')  { say 'Exiting...'; $exit = true }
+
+      loop do
+        result = nil
+
+        realtime = Benchmark.realtime do
+          result = Delayed::Job.work_off
+        end
+
+        count = result.sum
+
+        break if $exit
+
+        if count.zero?
+          sleep(SLEEP)
+        else
+          say "#{count} jobs processed at %.4f j/s, %d failed ..." % [count / realtime, result.last]
+        end
+
+        break if $exit
+      end
+
+    ensure
+      Delayed::Job.clear_locks!
+    end
+
+    def say(text)
+      puts text unless @quiet
+      logger.info text if logger
+    end
+
+  end
+end

data/lib/delayed_job.rb

@@ -0,0 +1,13 @@
+autoload :ActiveRecord, 'activerecord'
+
+require File.dirname(__FILE__) + '/delayed/message_sending'
+require File.dirname(__FILE__) + '/delayed/performable_method'
+require File.dirname(__FILE__) + '/delayed/job'
+require File.dirname(__FILE__) + '/delayed/worker'
+
+Object.send(:include, Delayed::MessageSending)   
+Module.send(:include, Delayed::MessageSending::ClassMethods)
+
+if defined?(Merb::Plugins)
+  Merb::Plugins.add_rakefiles File.dirname(__FILE__) / '..' / 'tasks' / 'tasks'
+end

data/spec/database.rb

@@ -0,0 +1,42 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+$:.unshift(File.dirname(__FILE__) + '/../../rspec/lib')
+
+require 'rubygems'
+require 'active_record'
+gem 'sqlite3-ruby'
+
+require File.dirname(__FILE__) + '/../init'
+require 'spec'
+  
+ActiveRecord::Base.logger = Logger.new('/tmp/dj.log')
+ActiveRecord::Base.establish_connection(:adapter => 'sqlite3', :database => '/tmp/jobs.sqlite')
+ActiveRecord::Migration.verbose = false
+
+ActiveRecord::Schema.define do
+
+  create_table :delayed_jobs, :force => true do |table|
+    table.integer  :priority, :default => 0
+    table.integer  :attempts, :default => 0
+    table.text     :handler
+    table.string   :last_error
+    table.datetime :run_at
+    table.datetime :locked_at
+    table.string   :locked_by
+    table.datetime :failed_at
+    table.timestamps
+  end
+
+  create_table :stories, :force => true do |table|
+    table.string :text
+  end
+
+end
+
+
+# Purely useful for test cases...
+class Story < ActiveRecord::Base
+  def tell; text; end       
+  def whatever(n, _); tell*n; end
+  
+  handle_asynchronously :whatever
+end

data/spec/delayed_method_spec.rb

@@ -0,0 +1,128 @@
+require File.dirname(__FILE__) + '/database'
+
+class SimpleJob
+  cattr_accessor :runs; self.runs = 0
+  def perform; @@runs += 1; end
+end
+
+class RandomRubyObject  
+  def say_hello
+    'hello'
+  end
+end
+
+class ErrorObject
+
+  def throw
+    raise ActiveRecord::RecordNotFound, '...'
+    false
+  end
+
+end
+
+class StoryReader
+
+  def read(story)
+    "Epilog: #{story.tell}"
+  end
+
+end
+
+class StoryReader
+
+  def read(story)
+    "Epilog: #{story.tell}"
+  end
+
+end
+
+describe 'random ruby objects' do
+  before       { Delayed::Job.delete_all }
+
+  it "should respond_to :send_later method" do
+
+    RandomRubyObject.new.respond_to?(:send_later)
+
+  end
+
+  it "should raise a ArgumentError if send_later is called but the target method doesn't exist" do
+    lambda { RandomRubyObject.new.send_later(:method_that_deos_not_exist) }.should raise_error(NoMethodError)
+  end
+
+  it "should add a new entry to the job table when send_later is called on it" do
+    Delayed::Job.count.should == 0
+
+    RandomRubyObject.new.send_later(:to_s)
+
+    Delayed::Job.count.should == 1
+  end
+
+  it "should add a new entry to the job table when send_later is called on the class" do
+    Delayed::Job.count.should == 0
+
+    RandomRubyObject.send_later(:to_s)
+
+    Delayed::Job.count.should == 1
+  end
+
+  it "should run get the original method executed when the job is performed" do
+
+    RandomRubyObject.new.send_later(:say_hello)
+
+    Delayed::Job.count.should == 1
+  end
+
+  it "should ignore ActiveRecord::RecordNotFound errors because they are permanent" do
+
+    ErrorObject.new.send_later(:throw)
+
+    Delayed::Job.count.should == 1
+
+    Delayed::Job.reserve_and_run_one_job
+
+    Delayed::Job.count.should == 0
+
+  end
+
+  it "should store the object as string if its an active record" do
+    story = Story.create :text => 'Once upon...'
+    story.send_later(:tell)
+
+    job =  Delayed::Job.find(:first)
+    job.payload_object.class.should   == Delayed::PerformableMethod
+    job.payload_object.object.should  == "AR:Story:#{story.id}"
+    job.payload_object.method.should  == :tell
+    job.payload_object.args.should    == []
+    job.payload_object.perform.should == 'Once upon...'
+  end
+
+  it "should store arguments as string if they an active record" do
+
+    story = Story.create :text => 'Once upon...'
+
+    reader = StoryReader.new
+    reader.send_later(:read, story)
+
+    job =  Delayed::Job.find(:first)
+    job.payload_object.class.should   == Delayed::PerformableMethod
+    job.payload_object.method.should  == :read
+    job.payload_object.args.should    == ["AR:Story:#{story.id}"]
+    job.payload_object.perform.should == 'Epilog: Once upon...'
+  end                 
+  
+  it "should call send later on methods which are wrapped with handle_asynchronously" do
+    story = Story.create :text => 'Once upon...'
+  
+    Delayed::Job.count.should == 0
+  
+    story.whatever(1, 5)
+  
+    Delayed::Job.count.should == 1
+    job =  Delayed::Job.find(:first)
+    job.payload_object.class.should   == Delayed::PerformableMethod
+    job.payload_object.method.should  == :whatever_without_send_later
+    job.payload_object.args.should    == [1, 5]
+    job.payload_object.perform.should == 'Once upon...'
+  end
+
+end

data/spec/job_spec.rb

@@ -0,0 +1,359 @@
+require File.dirname(__FILE__) + '/database'
+
+class SimpleJob
+  cattr_accessor :runs; self.runs = 0
+  def perform; @@runs += 1; end
+end
+
+class ErrorJob
+  cattr_accessor :runs; self.runs = 0
+  def perform; raise 'did not work'; end
+end             
+
+module M
+  class ModuleJob
+    cattr_accessor :runs; self.runs = 0
+    def perform; @@runs += 1; end    
+  end
+end
+
+class CustomJob < SimpleJob
+  def max_attempts; 3; end
+end
+
+describe Delayed::Job do
+  before  do               
+    Delayed::Job.max_priority = nil
+    Delayed::Job.min_priority = nil      
+    
+    Delayed::Job.delete_all
+  end
+  
+  before(:each) do
+    SimpleJob.runs = 0
+  end
+
+  it "should set run_at automatically if not set" do
+    Delayed::Job.create(:payload_object => ErrorJob.new ).run_at.should_not == nil
+  end
+
+  it "should not set run_at automatically if already set" do
+    later = 5.minutes.from_now
+    Delayed::Job.create(:payload_object => ErrorJob.new, :run_at => later).run_at.should == later
+  end
+
+  it "should raise ArgumentError when handler doesn't respond_to :perform" do
+    lambda { Delayed::Job.enqueue(Object.new) }.should raise_error(ArgumentError)
+  end
+
+  it "should increase count after enqueuing items" do
+    Delayed::Job.enqueue SimpleJob.new
+    Delayed::Job.count.should == 1
+  end
+
+  it "should be able to set priority when enqueuing items" do
+    Delayed::Job.enqueue SimpleJob.new, 5
+    Delayed::Job.first.priority.should == 5
+  end
+
+  it "should be able to set run_at when enqueuing items" do
+    later = 5.minutes.from_now
+    Delayed::Job.enqueue SimpleJob.new, 5, later
+
+    # use be close rather than equal to because millisecond values cn be lost in DB round trip
+    Delayed::Job.first.run_at.should be_close(later, 1)
+  end
+
+  it "should call perform on jobs when running work_off" do
+    SimpleJob.runs.should == 0
+
+    Delayed::Job.enqueue SimpleJob.new
+    Delayed::Job.work_off
+
+    SimpleJob.runs.should == 1
+  end
+                     
+                     
+  it "should work with eval jobs" do
+    $eval_job_ran = false
+
+    Delayed::Job.enqueue do <<-JOB
+      $eval_job_ran = true
+    JOB
+    end
+
+    Delayed::Job.work_off
+
+    $eval_job_ran.should == true
+  end
+                   
+  it "should work with jobs in modules" do
+    M::ModuleJob.runs.should == 0
+
+    Delayed::Job.enqueue M::ModuleJob.new
+    Delayed::Job.work_off
+
+    M::ModuleJob.runs.should == 1
+  end
+                   
+  it "should re-schedule by about 1 second at first and increment this more and more minutes when it fails to execute properly" do
+    Delayed::Job.enqueue ErrorJob.new
+    Delayed::Job.work_off(1)
+
+    job = Delayed::Job.find(:first)
+
+    job.last_error.should =~ /did not work/
+    job.last_error.should =~ /job_spec.rb:10:in `perform'/
+    job.attempts.should == 1
+
+    job.run_at.should > Delayed::Job.db_time_now - 10.minutes
+    job.run_at.should < Delayed::Job.db_time_now + 10.minutes
+  end
+
+  it "should raise an DeserializationError when the job class is totally unknown" do
+
+    job = Delayed::Job.new
+    job['handler'] = "--- !ruby/object:JobThatDoesNotExist {}"
+
+    lambda { job.payload_object.perform }.should raise_error(Delayed::DeserializationError)
+  end
+
+  it "should try to load the class when it is unknown at the time of the deserialization" do
+    job = Delayed::Job.new
+    job['handler'] = "--- !ruby/object:JobThatDoesNotExist {}"
+
+    job.should_receive(:attempt_to_load).with('JobThatDoesNotExist').and_return(true)
+
+    lambda { job.payload_object.perform }.should raise_error(Delayed::DeserializationError)
+  end
+
+  it "should try include the namespace when loading unknown objects" do
+    job = Delayed::Job.new
+    job['handler'] = "--- !ruby/object:Delayed::JobThatDoesNotExist {}"
+    job.should_receive(:attempt_to_load).with('Delayed::JobThatDoesNotExist').and_return(true)
+    lambda { job.payload_object.perform }.should raise_error(Delayed::DeserializationError)
+  end
+
+  it "should also try to load structs when they are unknown (raises TypeError)" do
+    job = Delayed::Job.new
+    job['handler'] = "--- !ruby/struct:JobThatDoesNotExist {}"
+
+    job.should_receive(:attempt_to_load).with('JobThatDoesNotExist').and_return(true)
+
+    lambda { job.payload_object.perform }.should raise_error(Delayed::DeserializationError)
+  end
+
+  it "should try include the namespace when loading unknown structs" do
+    job = Delayed::Job.new
+    job['handler'] = "--- !ruby/struct:Delayed::JobThatDoesNotExist {}"
+
+    job.should_receive(:attempt_to_load).with('Delayed::JobThatDoesNotExist').and_return(true)
+    lambda { job.payload_object.perform }.should raise_error(Delayed::DeserializationError)
+  end
+  
+  it "should be failed if it failed more than MAX_ATTEMPTS times and we don't want to destroy jobs" do
+    default = Delayed::Job.destroy_failed_jobs
+    Delayed::Job.destroy_failed_jobs = false
+
+    @job = Delayed::Job.create :payload_object => SimpleJob.new, :attempts => 50
+    @job.reload.failed_at.should == nil
+    @job.reschedule 'FAIL'
+    @job.reload.failed_at.should_not == nil
+
+    Delayed::Job.destroy_failed_jobs = default
+  end
+
+  it "should be destroyed if it failed more than MAX_ATTEMPTS times and we want to destroy jobs" do
+    default = Delayed::Job.destroy_failed_jobs
+    Delayed::Job.destroy_failed_jobs = true
+
+    @job = Delayed::Job.create :payload_object => SimpleJob.new, :attempts => 50
+    @job.should_receive(:destroy)
+    @job.reschedule 'FAIL'
+
+    Delayed::Job.destroy_failed_jobs = default
+  end
+  
+  it "should allow jobs to override max_attemps and behave appropriately" do
+    default = Delayed::Job.destroy_failed_jobs
+    Delayed::Job.destroy_failed_jobs = true
+
+    @job = Delayed::Job.create :payload_object => CustomJob.new, :attempts => 5
+    @job.should_receive(:destroy)
+    @job.reschedule 'FAIL'
+
+    Delayed::Job.destroy_failed_jobs = default
+  end
+
+  it "should never find failed jobs" do
+    @job = Delayed::Job.create :payload_object => SimpleJob.new, :attempts => 50, :failed_at => Time.now
+    Delayed::Job.find_available(1).length.should == 0
+  end
+
+  context "when another worker is already performing an task, it" do
+
+    before :each do
+      Delayed::Job.worker_name = 'worker1'
+      @job = Delayed::Job.create :payload_object => SimpleJob.new, :locked_by => 'worker1', :locked_at => Delayed::Job.db_time_now - 5.minutes
+    end
+
+    it "should not allow a second worker to get exclusive access" do
+      @job.lock_exclusively!(4.hours, 'worker2').should == false
+    end
+
+    it "should allow a second worker to get exclusive access if the timeout has passed" do
+      @job.lock_exclusively!(1.minute, 'worker2').should == true
+    end      
+    
+    it "should be able to get access to the task if it was started more then max_age ago" do
+      @job.locked_at = 5.hours.ago
+      @job.save
+
+      @job.lock_exclusively! 4.hours, 'worker2'
+      @job.reload
+      @job.locked_by.should == 'worker2'
+      @job.locked_at.should > 1.minute.ago
+    end
+
+    it "should not be found by another worker" do
+      Delayed::Job.worker_name = 'worker2'
+
+      Delayed::Job.find_available(1, 6.minutes).length.should == 0
+    end
+
+    it "should be found by another worker if the time has expired" do
+      Delayed::Job.worker_name = 'worker2'
+
+      Delayed::Job.find_available(1, 4.minutes).length.should == 1
+    end
+
+    it "should be able to get exclusive access again when the worker name is the same" do
+      @job.lock_exclusively! 5.minutes, 'worker1'
+      @job.lock_exclusively! 5.minutes, 'worker1'
+      @job.lock_exclusively! 5.minutes, 'worker1'
+    end                                        
+  end            
+  
+  context "#name" do
+    it "should be the class name of the job that was enqueued" do
+      Delayed::Job.create(:payload_object => ErrorJob.new ).name.should == 'ErrorJob'
+    end
+
+    it "should be the method that will be called if its a performable method object" do
+      Delayed::Job.send_later(:clear_locks!)
+      Delayed::Job.last.name.should == 'Delayed::Job.clear_locks!'
+
+    end
+    it "should be the instance method that will be called if its a performable method object" do
+      story = Story.create :text => "..."                 
+      
+      story.send_later(:save)
+      
+      Delayed::Job.last.name.should == 'Story#save'
+    end
+  end
+  
+  context "worker prioritization" do
+    
+    before(:each) do
+      Delayed::Job.max_priority = nil
+      Delayed::Job.min_priority = nil      
+    end
+  
+    it "should only work_off jobs that are >= min_priority" do
+      Delayed::Job.min_priority = -5
+      Delayed::Job.max_priority = 5
+      SimpleJob.runs.should == 0
+    
+      Delayed::Job.enqueue SimpleJob.new, -10
+      Delayed::Job.enqueue SimpleJob.new, 0
+      Delayed::Job.work_off
+    
+      SimpleJob.runs.should == 1
+    end
+  
+    it "should only work_off jobs that are <= max_priority" do
+      Delayed::Job.min_priority = -5
+      Delayed::Job.max_priority = 5
+      SimpleJob.runs.should == 0
+    
+      Delayed::Job.enqueue SimpleJob.new, 10
+      Delayed::Job.enqueue SimpleJob.new, 0
+
+      Delayed::Job.work_off
+
+      SimpleJob.runs.should == 1
+    end                         
+   
+  end
+  
+  context "when pulling jobs off the queue for processing, it" do
+    before(:each) do
+      @job = Delayed::Job.create(
+        :payload_object => SimpleJob.new, 
+        :locked_by => 'worker1', 
+        :locked_at => Delayed::Job.db_time_now - 5.minutes)
+    end
+
+    it "should leave the queue in a consistent state and not run the job if locking fails" do
+      SimpleJob.runs.should == 0     
+      @job.stub!(:lock_exclusively!).with(any_args).once.and_return(false)
+      Delayed::Job.should_receive(:find_available).once.and_return([@job])
+      Delayed::Job.work_off(1)
+      SimpleJob.runs.should == 0
+    end
+  
+  end
+  
+  context "while running alongside other workers that locked jobs, it" do
+    before(:each) do
+      Delayed::Job.worker_name = 'worker1'
+      Delayed::Job.create(:payload_object => SimpleJob.new, :locked_by => 'worker1', :locked_at => (Delayed::Job.db_time_now - 1.minutes))
+      Delayed::Job.create(:payload_object => SimpleJob.new, :locked_by => 'worker2', :locked_at => (Delayed::Job.db_time_now - 1.minutes))
+      Delayed::Job.create(:payload_object => SimpleJob.new)
+      Delayed::Job.create(:payload_object => SimpleJob.new, :locked_by => 'worker1', :locked_at => (Delayed::Job.db_time_now - 1.minutes))
+    end
+
+    it "should ingore locked jobs from other workers" do
+      Delayed::Job.worker_name = 'worker3'
+      SimpleJob.runs.should == 0
+      Delayed::Job.work_off
+      SimpleJob.runs.should == 1 # runs the one open job
+    end
+
+    it "should find our own jobs regardless of locks" do
+      Delayed::Job.worker_name = 'worker1'
+      SimpleJob.runs.should == 0
+      Delayed::Job.work_off
+      SimpleJob.runs.should == 3 # runs open job plus worker1 jobs that were already locked
+    end
+  end
+
+  context "while running with locked and expired jobs, it" do
+    before(:each) do
+      Delayed::Job.worker_name = 'worker1'
+      exp_time = Delayed::Job.db_time_now - (1.minutes + Delayed::Job::MAX_RUN_TIME)
+      Delayed::Job.create(:payload_object => SimpleJob.new, :locked_by => 'worker1', :locked_at => exp_time)
+      Delayed::Job.create(:payload_object => SimpleJob.new, :locked_by => 'worker2', :locked_at => (Delayed::Job.db_time_now - 1.minutes))
+      Delayed::Job.create(:payload_object => SimpleJob.new)
+      Delayed::Job.create(:payload_object => SimpleJob.new, :locked_by => 'worker1', :locked_at => (Delayed::Job.db_time_now - 1.minutes))
+    end
+
+    it "should only find unlocked and expired jobs" do
+      Delayed::Job.worker_name = 'worker3'
+      SimpleJob.runs.should == 0
+      Delayed::Job.work_off
+      SimpleJob.runs.should == 2 # runs the one open job and one expired job
+    end
+
+    it "should ignore locks when finding our own jobs" do
+      Delayed::Job.worker_name = 'worker1'
+      SimpleJob.runs.should == 0
+      Delayed::Job.work_off
+      SimpleJob.runs.should == 3 # runs open job plus worker1 jobs
+      # This is useful in the case of a crash/restart on worker1, but make sure multiple workers on the same host have unique names!
+    end
+
+  end
+  
+end

data/spec/story_spec.rb

@@ -0,0 +1,17 @@
+require File.dirname(__FILE__) + '/database'
+
+describe "A story" do
+
+  before(:all) do
+    @story = Story.create :text => "Once upon a time..."
+  end
+
+  it "should be shared" do
+    @story.tell.should == 'Once upon a time...'
+  end
+
+  it "should not return its result if it storytelling is delayed" do
+    @story.send_later(:tell).should_not == 'Once upon a time...'
+  end
+
+end

data/tasks/jobs.rake

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__), 'tasks')

data/tasks/tasks.rb

@@ -0,0 +1,15 @@
+# Re-definitions are appended to existing tasks
+task :environment
+task :merb_env
+
+namespace :jobs do
+  desc "Clear the delayed_job queue."
+  task :clear => [:merb_env, :environment] do
+    Delayed::Job.delete_all
+  end
+
+  desc "Start a delayed_job worker."
+  task :work => [:merb_env, :environment] do
+    Delayed::Worker.new(:min_priority => ENV['MIN_PRIORITY'], :max_priority => ENV['MAX_PRIORITY']).start
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification 
+name: dburkes-delayed_job
+version: !ruby/object:Gem::Version 
+  version: 1.7.0
+platform: ruby
+authors: 
+- "Tobias L\xC3\xBCtke"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-11-28 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: Delated_job (or DJ) encapsulates the common pattern of asynchronously executing longer tasks in the background. It is a direct extraction from Shopify where the job table is responsible for a multitude of core tasks.
+email: tobi@leetsoft.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.textile
+files: 
+- MIT-LICENSE
+- README.textile
+- delayed_job.gemspec
+- init.rb
+- lib/delayed/job.rb
+- lib/delayed/message_sending.rb
+- lib/delayed/performable_method.rb
+- lib/delayed/worker.rb
+- lib/delayed_job.rb
+- tasks/jobs.rake
+- tasks/tasks.rb
+has_rdoc: false
+homepage: http://github.com/tobi/delayed_job/tree/master
+post_install_message: 
+rdoc_options: 
+- --main
+- README.textile
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Database-backed asynchronous priority queue system -- Extracted from Shopify
+test_files: 
+- spec/database.rb
+- spec/delayed_method_spec.rb
+- spec/job_spec.rb
+- spec/story_spec.rb