keithmgould-delayed_job 1.7.1

data/.gitignore

@@ -0,0 +1 @@
+*.gem

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,121 @@
+h1. Delayed::Job
+
+Delayed_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 can be created by using:
+<pre><code>
+  script/generate delayed_job_migration
+</code></pre>
+
+The created table looks as follows: 
+
+<pre><code>
+  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
+</code></pre>
+
+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@. 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:
+
+<pre><code>
+  # 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
+</code></pre>
+
+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. 
+
+<pre><code>
+  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))
+</code></pre>
+
+There is also a second way to get jobs in the queue: send_later. 
+
+<pre><code>
+  BatchImporter.new(Shop.find(1)).send_later(:import_massive_csv, massive_csv)
+</code></pre>
+
+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/Rakefile

@@ -0,0 +1,13 @@
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "keithmgould-delayed_job"
+    gemspec.summary = "Database-backed asynchronous priority queue system -- Extracted from Shopify"
+    gemspec.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.  Augmented by Keith to allows for callbacks on idle."
+    gemspec.email = "keith@dailymugshot.com"
+    gemspec.homepage = "http://github.com/keithmgould/delayed_job"
+    gemspec.authors = ["Tobias Lütke", "Keith Gould"]
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end

data/VERSION

@@ -0,0 +1 @@
+1.7.1

data/generators/delayed_job_migration/delayed_job_migration_generator.rb

@@ -0,0 +1,15 @@
+class DelayedJobMigrationGenerator < Rails::Generator::Base
+  def manifest
+    record do |m|
+      options = {
+        :migration_file_name => 'create_delayed_jobs'
+      }
+
+      m.migration_template 'migration.rb', 'db/migrate', options
+    end
+  end
+  
+  def banner
+    "Usage: #{$0} #{spec.name}"
+  end
+end

data/generators/delayed_job_migration/templates/migration.rb

@@ -0,0 +1,22 @@
+class CreateDelayedJobs < ActiveRecord::Migration
+  def self.up
+    create_table :delayed_jobs, :force => true do |t|
+      t.integer  :priority, :default => 0      # Allows some jobs to jump to the front of the queue
+      t.integer  :attempts, :default => 0      # Provides for retries, but still fail eventually.
+      t.text     :handler                      # YAML-encoded string of the object that will do work
+      t.string   :last_error                   # reason for last failure (See Note below)
+      t.datetime :run_at                       # When to run. Could be Time.now for immediately, or sometime in the future.
+      t.datetime :locked_at                    # Set when a client is working on this object
+      t.datetime :failed_at                    # Set when all retries have failed (actually, by default, the record is deleted instead)
+      t.string   :locked_by                    # Who is working on this object (if locked)
+
+      t.timestamps
+    end
+
+    add_index :delayed_jobs, :locked_by
+  end
+
+  def self.down
+    drop_table :delayed_jobs
+  end
+end

data/init.rb

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

data/keithmgould-delayed_job.gemspec

@@ -0,0 +1,64 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{keithmgould-delayed_job}
+  s.version = "1.7.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Tobias L\303\274tke", "Keith Gould"]
+  s.date = %q{2010-04-27}
+  s.description = %q{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.  Augmented by Keith to allows for callbacks on idle.}
+  s.email = %q{keith@dailymugshot.com}
+  s.extra_rdoc_files = [
+    "README.textile"
+  ]
+  s.files = [
+    ".gitignore",
+     "MIT-LICENSE",
+     "README.textile",
+     "Rakefile",
+     "VERSION",
+     "generators/delayed_job_migration/delayed_job_migration_generator.rb",
+     "generators/delayed_job_migration/templates/migration.rb",
+     "init.rb",
+     "keithmgould-delayed_job.gemspec",
+     "lib/delayed/job.rb",
+     "lib/delayed/message_sending.rb",
+     "lib/delayed/performable_method.rb",
+     "lib/delayed/worker.rb",
+     "lib/delayed_job.rb",
+     "spec/database.rb",
+     "spec/delayed_method_spec.rb",
+     "spec/job_spec.rb",
+     "spec/story_spec.rb",
+     "spec/worker_spec.rb",
+     "tasks/jobs.rake",
+     "tasks/tasks.rb"
+  ]
+  s.homepage = %q{http://github.com/keithmgould/delayed_job}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{Database-backed asynchronous priority queue system -- Extracted from Shopify}
+  s.test_files = [
+    "spec/database.rb",
+     "spec/delayed_method_spec.rb",
+     "spec/job_spec.rb",
+     "spec/story_spec.rb",
+     "spec/worker_spec.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

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 < 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, Delayed::Job.db_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.zone.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,70 @@
+module Delayed
+  class Worker
+    SLEEP = 5
+
+    attr_reader :idle_after, :next_idle
+    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]
+      @idle_after = options[:idle_after] || 60
+      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 }
+      
+      @next_idle = Time.new + @idle_after
+      
+      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
+          @next_idle = Time.new + @idle_after
+          say "#{count} jobs processed at %.4f j/s, %d failed ..." % [count / realtime, result.last]
+        end
+        
+        if Time.new > @next_idle
+          @next_idle = Time.new + @idle_after
+          on_idle
+        end
+        
+        break if $exit
+      end
+
+    ensure
+      Delayed::Job.clear_locks!
+    end
+
+    def say(text)
+      puts text unless @quiet
+      logger.info text if logger
+    end
+    
+    private
+    
+    def on_idle
+      # You may overide this callback method
+    end
+
+  end
+end