unique_delayed_job 0.0.1 → 0.1.0

data/README

@@ -12,19 +12,55 @@ duplicate key is raised on insert, then the insert will just be ignored. There
 are factory methods for creating a delayed job in the following ways:
 * with a delayed job handler class (one that responds to perform())
 * with an object, method and method arguments
-* with a code block
+* with a string to be evaled see the Delayed::Job.enqueue() method that accepts
+  a block. (looks like the idea may have been added to delayed job here:
+  http://github.com/dhh/delayed_job/commit/89c3a0b77470c0f8510d3c7a51a36cd07747d9a9)
+  the block is yielded to, and the result (assumed to be a string) is stored as
+  the code to be evaled when the job is deserialized.
+
+== Configuration
+
+You can add whatever columns you need to the delayed_jobs table, and put any
+uniqueness constraints (or not) on them as you wish (unique columns, unique
+composite keys etc.).
+
+Note that by default, UniqueDelayedJob will modify any jobs that are currently locked
+(locked_by is not null)...it will set all of the additional columns specified
+on the job to NULL. (This allows for inserting a new job if a matching job is
+already in process--and thus might be using out-of-date data.) If you do NOT
+want this behavior, and do not want to insert a matching job if another job is
+currently locked/being run, then make the following call. If you like, you can
+change this before/after every job you insert if you want different jobs
+to use different policies.
+
+  UniqueDelayedJob.do_not_mark_locked_jobs_with_null()
 
 == Examples
 
-# use a custom handler
-job = Delayed::UniqueDelayedJob.use_handler(MyHandlerClass.new( ...), :user_id => 123)
-job.enqueue  # use default priority and run_at
+In each example below, the :user_id => 123 is just to illustrate that you can add
+arbitrary additional column(s) to the delayed job row being inserted. Presumably,
+the user_id column has uniqueness constraints on it...
+
+(More than one column could be specified; uniqueness is enforced by the db schema,
+and unique delayed job just catches and swallows any duplicate key exceptions.)
+
+  # use a custom handler
+  job = Delayed::UniqueDelayedJob.use_handler(MyHandlerClass.new( ...), :user_id => 123)
+  job.enqueue  # use default priority and run_at
 
-# use a method call (similar to using send_later on the object)
-record = MyActiveRecord.find(1)
-job = Delayed::UniqueDelayedJob.call_method(record, :a_method, [arg1, arg2], :user_id => 123)
-job.enqueue(1) # use priority of 1
+  # use a method call (similar to using send_later on the object)
+  record = MyActiveRecord.find(1)
+  job = Delayed::UniqueDelayedJob.call_method(record,
+                                              :a_method,
+                                              [arg1, arg2],
+                                              :user_id => 123)
+  job.enqueue(1) # use priority of 1
 
-# use a code block
-job = Delayed::UniqueDelayedJob.run_block(:user_id => 123) { run_some_code }
-job.enqueue(2, 1.hour.from_now) # priority 1, run at 1 hour from now
+  # specify a block of code to execute with string (inside a block)
+  # note that the block could be complex logic that results in a string that is
+  # arbitrary ruby code to be evaled
+  # see Delayed::Job::enqueue(args, &block)
+  job = Delayed::UniqueDelayedJob.run_eval(:user_id => 123) do
+    'SomeClass.perform_some_slow_action'
+  end
+  job.enqueue(2, 1.hour.from_now) # run with priority 2 and run at 1 hour from now

data/lib/delayed/unique_delayed_job.rb

@@ -0,0 +1,157 @@
+module Delayed
+
+  # allows for specifying additional columns on the delayed_jobs table to help
+  # prevent duplicate delayed jobs from being entered into the queue...but still
+  # keep an easy interface to enqueuing delayed jobs
+  #-----------------------------------------------------------------------------
+  class UniqueDelayedJob
+
+    cattr_reader :mark_all_locked_jobs_with_null
+
+    @@mark_all_locked_jobs_with_null = true
+
+    # enable the polciy that all delayed job rows that are marked with non-null
+    # locked_by should have their columns set to null...ensuring that if a
+    # job is currently executing then we CAN insert another delayed job with
+    # the same unique keys.
+    # This is useful if you want to run a job every time some event occurs, but
+    # you're using this gem just to prevent having the same job twice in the
+    # queue. But if a job is currently running, it may miss the change in state
+    # due to the latest event, so a new job does need to be added to the queue.
+    # setting the columns to null on any jobs currently locked should 
+    # ensure this behavior.
+    # This is the default behavior.
+    #-----------------------------------------------------------------------------
+    def self.mark_all_locked_jobs_with_null
+      @mark_all_locked_jobs_with_null = true
+    end
+
+    # override the default behavior, and DO NOT mark the columns on a delayed
+    # job that is currently locked to null. this prevents inserting a duplicate
+    # job with a job that is currently running (e.g. if you only want to run
+    # the job once). Default is mark_all_locked_jobs_with_null (see that method)
+    #-----------------------------------------------------------------------------
+    def self.do_not_mark_locked_jobs_with_null
+      @mark_all_locked_jobs_with_null = false
+    end
+
+
+    # factory method to create a new UniqueDelayedJob from a delayed job handler
+    # object (see delayed job documentation for requirements)
+    #
+    # arguments:
+    #    - handler: the delayed jobs handler object you're using
+    #    - columns: hash of column names and values to insert into the delayed
+    #               jobs table in addition to the handler
+    #---------------------------------------------------------------------------
+    def self.use_handler(handler, columns = {})
+      job = self.new(handler, columns)
+    end
+
+
+    # factory method to create a new UniqueDelayedJob by specifying a method ton
+    # call. will use delayed jobs' PerformableMethod class to enqueue the job
+    #
+    # arguments:
+    #    - object: the object (or class or module) on which to call the method
+    #    - method: the method to call (specify a symbol or string)
+    #    - args_arr: an array of arguments to pass in the method call)
+    #    - columns: hash of column names and values to insert into the delayed
+    #               jobs table in addition to the handler
+    #---------------------------------------------------------------------------
+    def self.call_method(object, method, args_arr, columns = {})
+      job = self.new(Delayed::PerformableMethod.new(object, method, args_arr),
+                     columns)
+    end
+
+
+    # factory method to create a UniqueDelayedJob by specifying a block that
+    # is executed and whose result is stored as a string to be evaled by
+    # delayed_job
+    # arguments:
+    #    - columns: hash of column names and values to insert into the delayed
+    #               jobs table in addition to the handler
+    # NOTE: a block is expected
+    #---------------------------------------------------------------------------
+    def self.run_eval(columns = {}, &block)
+      raise "missing a block in call to run_block" if !block_given?
+      job = self.new(Delayed::EvaledJob.new(&block), columns)
+    end
+
+
+    # specify some additional columns to set in the delayed jobs table for this
+    # row. be sure that you've migrated to add these columns to the delayed jobs
+    # table. it is up to you to specify uniqueness constraints on any of the
+    # columns you'd like to use to prevent duplicate entries in the delayed jobs
+    # table. (it's also fine for some of these columns to not have unique
+    # constraints, though this class will not prevent duplicate values for those
+    # and they'll be for your use for other purposes.)
+    #---------------------------------------------------------------------------
+    def add_delayed_jobs_columns(new_columns)
+      columns.merge! new_columns
+    end
+
+
+    # put the job on the delayed jobs queue. if there already is a row in the
+    # delayed jobs table with the same value in any of the unique columns
+    # (enforced in the db), then the row will not be inserted
+    #
+    # return value:
+    #   - if a new delayed job is inserted, the job object is returned
+    #   - otherwise, returns nil
+    #
+    # arguments:
+    #    priority: 
+    #    run_at: 
+    #---------------------------------------------------------------------------
+    def enqueue(priority = nil, run_at = nil)
+      if mark_all_locked_jobs_with_null && !columns.blank?
+        null_setting_strings = []
+
+        columns.each_key do |c|
+          null_setting_strings << "#{c.to_s} = NULL"
+        end
+
+        Delayed::Job.update_all(null_setting_strings.join("\n              ,"),
+                                "locked_by IS NOT NULL")
+      end
+
+      cols_to_insert = columns
+      cols_to_insert.merge! :priority => priority if priority
+      cols_to_insert.merge! :run_at => run_at if run_at
+      cols_to_insert.merge! :handler => handler
+
+      job = nil
+
+      # try to catch if this raises an exception because of a duplicate key
+      # error this should work for mysql and postgresql which both have the
+      # word 'duplicate' followed (not necessarily immediately) by 'key'.
+      # ignoring case cause case differs between the two cases
+      # if doesn't look like a dupe key error, then reraise the exception
+      begin
+        job = Delayed::Job.create(cols_to_insert)
+      rescue => e
+        if /(duplicate).*(key)/i !~ e.message
+          raise e
+        end
+      end
+
+      return job
+    end
+
+    attr_accessor :columns
+
+  protected
+
+    attr_accessor :handler
+
+    # constructor used by the factory methods
+    #---------------------------------------------------------------------------
+    def initialize(handler, columns = {})
+      @handler = handler
+      @columns = columns
+    end
+
+  end
+
+end

data/lib/unique_delayed_job.rb

@@ -1,116 +1 @@
-module Delayed
-
-  # allows for specifying additional columns on the delayed_jobs table to help
-  # prevent duplicate delayed jobs from being entered into the queue...but still
-  # keep an easy interface to enqueuing delayed jobs
-  #-----------------------------------------------------------------------------
-  class UniqueDelayedJob
-
-    # factory method to create a new UniqueDelayedJob from a delayed job handler
-    # object (see delayed job documentation for requirements)
-    #
-    # arguments:
-    #    - handler: the delayed jobs handler object you're using
-    #    - columns: hash of column names and values to insert into the delayed
-    #               jobs table in addition to the handler
-    #---------------------------------------------------------------------------
-    def self.use_handler(handler, columns = {})
-      job = self.new
-      job.handler = handler
-
-      job
-    end
-
-    # factory method to create a new UniqueDelayedJob by specifying a method ton
-    # call. will use delayed jobs' PerformableMethod class to enqueue the job
-    #
-    # arguments:
-    #    - object: the object (or class or module) on which to call the method
-    #    - method: the method to call (specify a symbol or string)
-    #    - args_arr: an array of arguments to pass in the method call)
-    #    - columns: hash of column names and values to insert into the delayed
-    #               jobs table in addition to the handler
-    #---------------------------------------------------------------------------
-    def self.call_method(object, method, args_arr, columns = {})
-      job = self.new
-      job.handler = Delayed::PerformableMethod.new(object, method, args_arr)
-
-      job
-    end
-
-
-    # factory method to create a UniqueDelayedJob by specifying a block to
-    # execute asynchronously
-    # arguments:
-    #    - columns: hash of column names and values to insert into the delayed
-    #               jobs table in addition to the handler
-    # NOTE: a block is expected
-    #---------------------------------------------------------------------------
-    def self.run_block(columns = {}, &block)
-      raise "missing a block in call to run_block" if !block_given?
-      job = self.new
-      job.handler = Delayed::EvaledJob.new(&block)
-
-      job
-    end
-
-
-    # specify some additional columns to set in the delayed jobs table for this
-    # row. be sure that you've migrated to add these columns to the delayed jobs
-    # table. it is up to you to specify uniqueness constraints on any of the
-    # columns you'd like to use to prevent duplicate entries in the delayed jobs
-    # table. (it's also fine for some of these columns to not have unique
-    # constraints, though this class will not prevent duplicate values for those
-    # and they'll be for your use for other purposes.)
-    #---------------------------------------------------------------------------
-    def add_delayed_jobs_columns(new_columns)
-      columns.merge! new_columns
-    end
-
-    # put the job on the delayed jobs queue. if there already is a row in the
-    # delayed jobs table with the same value in any of the unique columns
-    # (enforced in the db), then the row will not be inserted
-    #
-    # arguments:
-    #    priority: 
-    #    run_at: 
-    #---------------------------------------------------------------------------
-    def enqueue(priority = nil, run_at = nil)
-      cols_to_insert = columns
-      cols_to_insert.merge! :priority => priority if priority
-      cols_to_insert.merge! :run_at => run_at if run_at
-      cols_to_insert.merge! :handler => handler
-
-      # try to catch if this raises an exception because of a duplicate key
-      # error this should work for mysql and postgresql which both have the
-      # word 'duplicate' followed (not necessarily immediately) by 'key'.
-      # ignoring case cause case differs between the two cases
-      # if doesn't look like a dupe key error, then reraise the exception
-      begin
-        Delayed::Job.create(cols_to_insert)
-      rescue => e
-        if /(duplicate).*(key)/i !~ e.message
-          raise e
-        end
-      end
-
-    end
-
-    attr_accessor :columns
-
-    protected
-
-    attr_accessor :handler
-
-
-    # constructor used by the factory methods
-    #---------------------------------------------------------------------------
-    def initialize(handler, columns = {})
-      @handler = nil
-      @call_method = { :method => nil, args => nil }
-      @columns = {}
-    end
-
-  end
-
-end
+require 'delayed/unique_delayed_job'

data/unique_delayed_job.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{unique_delayed_job}
-  s.version = "0.0.1"
+  s.version = "0.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Brian Percival"]
-  s.date = %q{2009-11-18}
+  s.date = %q{2009-11-19}
   s.description = %q{Class for creating delayed jobs that can be de-duped with existing delayed jobs
 already in the delayed jobs table. You just specify some additional columns on
 your delayed_jobs table and set them to have uniqueness constraints. Then
@@ -18,7 +18,7 @@ duplicate key is raised on insert, then the insert will just be ignored. There
 are factory methods for creating a delayed job in the following ways:
 * with a delayed job handler class (one that responds to perform())
 * with an object, method and method arguments
-* with a code block
+* with a code string to be evaled
 
 NOTE: you must have delayed_job installed as a gem or plugin
 }
@@ -27,7 +27,8 @@ NOTE: you must have delayed_job installed as a gem or plugin
     "README"
   ]
   s.files = [
-    "lib/unique_delayed_job.rb",
+    "lib/delayed/unique_delayed_job.rb",
+     "lib/unique_delayed_job.rb",
      "unique_delayed_job.gemspec"
   ]
   s.homepage = %q{http://github.com/bmpercy/unique_delayed_job}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: unique_delayed_job
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors: 
 - Brian Percival
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-18 00:00:00 -08:00
+date: 2009-11-19 00:00:00 -08:00
 default_executable: 
 dependencies: []
 
@@ -22,7 +22,7 @@ description: |
   are factory methods for creating a delayed job in the following ways:
   * with a delayed job handler class (one that responds to perform())
   * with an object, method and method arguments
-  * with a code block
+  * with a code string to be evaled
   
   NOTE: you must have delayed_job installed as a gem or plugin
 
@@ -34,6 +34,7 @@ extensions: []
 extra_rdoc_files: 
 - README
 files: 
+- lib/delayed/unique_delayed_job.rb
 - lib/unique_delayed_job.rb
 - unique_delayed_job.gemspec
 - README