activejob 4.2.0.beta1 → 4.2.0.beta2

data/lib/active_job/execution.rb

@@ -4,15 +4,29 @@ require 'active_job/arguments'
 module ActiveJob
   module Execution
     extend ActiveSupport::Concern
+    include ActiveSupport::Rescuable
 
-    included do
-      include ActiveSupport::Rescuable
-    end
+    module ClassMethods
+      # Performs the job immediately.
+      #
+      #   MyJob.perform_now("mike")
+      #
+      def perform_now(*args)
+        job_or_instantiate(*args).perform_now
+      end
 
-    def execute(job_id, *serialized_args)
-      self.job_id    = job_id
-      self.arguments = deserialize_arguments(serialized_args)
+      def execute(job_data) #:nodoc:
+        job = deserialize(job_data)
+        job.perform_now
+      end
+    end
 
+    # Performs the job immediately. The job is not sent to the queueing adapter
+    # but directly executed by blocking the execution of others until it's finished.
+    #
+    #   MyJob.new(*args).perform_now
+    def perform_now
+      deserialize_arguments_if_needed
       run_callbacks :perform do
         perform(*arguments)
       end
@@ -23,11 +37,5 @@ module ActiveJob
     def perform(*)
       fail NotImplementedError
     end
-
-    private
-      def deserialize_arguments(serialized_args)
-        Arguments.deserialize(serialized_args)
-      end
-
   end
 end

data/lib/active_job/gem_version.rb

@@ -1,5 +1,5 @@
 module ActiveJob
-  # Returns the version of the currently loaded ActiveJob as a <tt>Gem::Version</tt>
+  # Returns the version of the currently loaded Active Job as a <tt>Gem::Version</tt>
   def self.gem_version
     Gem::Version.new VERSION::STRING
   end
@@ -8,7 +8,7 @@ module ActiveJob
     MAJOR = 4
     MINOR = 2
     TINY  = 0
-    PRE   = "beta1"
+    PRE   = "beta2"
 
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")
   end

data/lib/active_job/logging.rb

@@ -17,7 +17,7 @@ module ActiveJob
 
       around_perform do |job, block, _|
         tag_logger(job.class.name, job.job_id) do
-          payload = {adapter: job.class.queue_adapter, job: job.class, args: job.arguments}
+          payload = {adapter: job.class.queue_adapter, job: job}
           ActiveSupport::Notifications.instrument("perform_start.active_job", payload.dup)
           ActiveSupport::Notifications.instrument("perform.active_job", payload) do
             block.call
@@ -26,12 +26,12 @@ module ActiveJob
       end
 
       before_enqueue do |job|
-        if job.enqueued_at
+        if job.scheduled_at
           ActiveSupport::Notifications.instrument "enqueue_at.active_job",
-            adapter: job.class.queue_adapter, job: job.class, job_id: job.job_id, args: job.arguments, timestamp: job.enqueued_at
+            adapter: job.class.queue_adapter, job: job
         else
           ActiveSupport::Notifications.instrument "enqueue.active_job",
-            adapter: job.class.queue_adapter, job: job.class, job_id: job.job_id, args: job.arguments
+            adapter: job.class.queue_adapter, job: job
         end
       end
     end
@@ -50,21 +50,33 @@ module ActiveJob
         logger.formatter.current_tags.include?("ActiveJob")
       end
 
-    class LogSubscriber < ActiveSupport::LogSubscriber
+    class LogSubscriber < ActiveSupport::LogSubscriber #:nodoc:
       def enqueue(event)
-        info "Enqueued #{event.payload[:job].name} (Job ID: #{event.payload[:job_id]}) to #{queue_name(event)}" + args_info(event)
+        info do
+          job = event.payload[:job]
+          "Enqueued #{job.class.name} (Job ID: #{job.job_id}) to #{queue_name(event)}" + args_info(job)
+        end
       end
 
       def enqueue_at(event)
-        info "Enqueued #{event.payload[:job].name} (Job ID: #{event.payload[:job_id]}) to #{queue_name(event)} at #{enqueued_at(event)}" + args_info(event)
+        info do
+          job = event.payload[:job]
+          "Enqueued #{job.class.name} (Job ID: #{job.job_id}) to #{queue_name(event)} at #{scheduled_at(event)}" + args_info(job)
+        end
       end
 
       def perform_start(event)
-        info "Performing #{event.payload[:job].name} from #{queue_name(event)}" + args_info(event)
+        info do
+          job = event.payload[:job]
+          "Performing #{job.class.name} from #{queue_name(event)}" + args_info(job)
+        end
       end
 
       def perform(event)
-        info "Performed #{event.payload[:job].name} from #{queue_name(event)} in #{event.duration.round(2).to_s}ms"
+        info do
+          job = event.payload[:job]
+          "Performed #{job.class.name} from #{queue_name(event)} in #{event.duration.round(2).to_s}ms"
+        end
       end
 
       private
@@ -72,12 +84,12 @@ module ActiveJob
           event.payload[:adapter].name.demodulize.remove('Adapter') + "(#{event.payload[:job].queue_name})"
         end
 
-        def args_info(event)
-          event.payload[:args].any? ? " with arguments: #{event.payload[:args].map(&:inspect).join(", ")}" : ""
+        def args_info(job)
+          job.arguments.any? ? " with arguments: #{job.arguments.map(&:inspect).join(", ")}" : ""
         end
 
-        def enqueued_at(event)
-          Time.at(event.payload[:timestamp]).utc
+        def scheduled_at(event)
+          Time.at(event.payload[:job].scheduled_at).utc
         end
 
         def logger

data/lib/active_job/queue_adapter.rb

@@ -3,22 +3,27 @@ require 'active_support/core_ext/string/inflections'
 
 module ActiveJob
   module QueueAdapter
-    mattr_reader(:queue_adapter) { ActiveJob::QueueAdapters::InlineAdapter }
+    extend ActiveSupport::Concern
 
-    def queue_adapter=(name_or_adapter)
-      @@queue_adapter = \
-        case name_or_adapter
-        when Symbol, String
-          load_adapter(name_or_adapter)
-        when Class
-          name_or_adapter
-        end
-    end
+    module ClassMethods
+      mattr_reader(:queue_adapter) { ActiveJob::QueueAdapters::InlineAdapter }
 
-    private
-      def load_adapter(name)
-        require "active_job/queue_adapters/#{name}_adapter"
-        "ActiveJob::QueueAdapters::#{name.to_s.camelize}Adapter".constantize
+      def queue_adapter=(name_or_adapter)
+        @@queue_adapter = \
+          case name_or_adapter
+          when :test
+            ActiveJob::QueueAdapters::TestAdapter.new
+          when Symbol, String
+            load_adapter(name_or_adapter)
+          when Class
+            name_or_adapter
+          end
       end
+
+      private
+        def load_adapter(name)
+          "ActiveJob::QueueAdapters::#{name.to_s.camelize}Adapter".constantize
+        end
+    end
   end
 end

data/lib/active_job/queue_adapters.rb

@@ -0,0 +1,51 @@
+module ActiveJob
+  # == Active Job adapters
+  #
+  # Active Job has adapters for the following queueing backends:
+  #
+  # * {Backburner}[https://github.com/nesquena/backburner]
+  # * {Delayed Job}[https://github.com/collectiveidea/delayed_job]
+  # * {Qu}[https://github.com/bkeepers/qu]
+  # * {Que}[https://github.com/chanks/que]
+  # * {QueueClassic 2.x}[https://github.com/ryandotsmith/queue_classic/tree/v2.2.3]
+  # * {Resque 1.x}[https://github.com/resque/resque/tree/1-x-stable]
+  # * {Sidekiq}[http://sidekiq.org]
+  # * {Sneakers}[https://github.com/jondot/sneakers]
+  # * {Sucker Punch}[https://github.com/brandonhilkert/sucker_punch]
+  #
+  # #### Backends Features
+  #
+  #   |                   | Async | Queues | Delayed   | Priorities | Timeout | Retries |
+  #   |-------------------|-------|--------|-----------|------------|---------|---------|
+  #   | Backburner        | Yes   | Yes    | Yes       | Yes        | Job     | Global  |
+  #   | Delayed Job       | Yes   | Yes    | Yes       | Job        | Global  | Global  |
+  #   | Que               | Yes   | Yes    | Yes       | Job        | No      | Job     |
+  #   | Queue Classic     | Yes   | Yes    | No*       | No         | No      | No      |
+  #   | Resque            | Yes   | Yes    | Yes (Gem) | Queue      | Global  | Yes     |
+  #   | Sidekiq           | Yes   | Yes    | Yes       | Queue      | No      | Job     |
+  #   | Sneakers          | Yes   | Yes    | No        | Queue      | Queue   | No      |
+  #   | Sucker Punch      | Yes   | Yes    | No        | No         | No      | No      |
+  #   | Active Job Inline | No    | Yes    | N/A       | N/A        | N/A     | N/A     |
+  #   | Active Job        | Yes   | Yes    | Yes       | No         | No      | No      |
+  #
+  # NOTE:
+  # Queue Classic does not support Job scheduling. However you can implement this
+  # yourself or you can use the queue_classic-later gem. See the documentation for
+  # ActiveJob::QueueAdapters::QueueClassicAdapter.
+  #
+  module QueueAdapters
+    extend ActiveSupport::Autoload
+
+    autoload :InlineAdapter
+    autoload :BackburnerAdapter
+    autoload :DelayedJobAdapter
+    autoload :QuAdapter
+    autoload :QueAdapter
+    autoload :QueueClassicAdapter
+    autoload :ResqueAdapter
+    autoload :SidekiqAdapter
+    autoload :SneakersAdapter
+    autoload :SuckerPunchAdapter
+    autoload :TestAdapter
+  end
+end

data/lib/active_job/queue_adapters/backburner_adapter.rb

@@ -2,21 +2,32 @@ require 'backburner'
 
 module ActiveJob
   module QueueAdapters
+    # == Backburner adapter for Active Job
+    #
+    # Backburner is a beanstalkd-powered job queue that can handle a very
+    # high volume of jobs. You create background jobs and place them on
+    # multiple work queues to be processed later. Read more about
+    # Backburner {here}[https://github.com/nesquena/backburner].
+    #
+    # To use Backburner set the queue_adapter config to +:backburner+.
+    #
+    #   Rails.application.config.active_job.queue_adapter = :backburner
     class BackburnerAdapter
       class << self
-        def enqueue(job, *args)
-          Backburner::Worker.enqueue JobWrapper, [ job.name, *args ], queue: job.queue_name
+        def enqueue(job) #:nodoc:
+          Backburner::Worker.enqueue JobWrapper, [ job.serialize ], queue: job.queue_name
         end
 
-        def enqueue_at(job, timestamp, *args)
-          raise NotImplementedError
+        def enqueue_at(job, timestamp) #:nodoc:
+          delay = timestamp - Time.current.to_f
+          Backburner::Worker.enqueue JobWrapper, [ job.serialize ], queue: job.queue_name, delay: delay
         end
       end
 
-      class JobWrapper
+      class JobWrapper #:nodoc:
         class << self
-          def perform(job_name, *args)
-            job_name.constantize.new.execute(*args)
+          def perform(job_data)
+            Base.execute job_data
           end
         end
       end

data/lib/active_job/queue_adapters/delayed_job_adapter.rb

@@ -2,20 +2,36 @@ require 'delayed_job'
 
 module ActiveJob
   module QueueAdapters
+    # == Delayed Job adapter for Active Job
+    #
+    # Delayed::Job (or DJ) encapsulates the common pattern of asynchronously
+    # executing longer tasks in the background. Although DJ can have many
+    # storage backends one of the most used is based on Active Record.
+    # Read more about Delayed Job {here}[https://github.com/collectiveidea/delayed_job].
+    #
+    # To use Delayed Job set the queue_adapter config to +:delayed_job+.
+    #
+    #   Rails.application.config.active_job.queue_adapter = :delayed_job
     class DelayedJobAdapter
       class << self
-        def enqueue(job, *args)
-          JobWrapper.new.delay(queue: job.queue_name).perform(job, *args)
+        def enqueue(job) #:nodoc:
+          Delayed::Job.enqueue(JobWrapper.new(job.serialize), queue: job.queue_name)
         end
 
-        def enqueue_at(job, timestamp, *args)
-          JobWrapper.new.delay(queue: job.queue_name, run_at: Time.at(timestamp)).perform(job, *args)
+        def enqueue_at(job, timestamp) #:nodoc:
+          Delayed::Job.enqueue(JobWrapper.new(job.serialize), queue: job.queue_name, run_at: Time.at(timestamp))
         end
       end
 
-      class JobWrapper
-        def perform(job, *args)
-          job.new.execute(*args)
+      class JobWrapper #:nodoc:
+        attr_accessor :job_data
+
+        def initialize(job_data)
+          @job_data = job_data
+        end
+
+        def perform
+          Base.execute(job_data)
         end
       end
     end

data/lib/active_job/queue_adapters/inline_adapter.rb

@@ -1,12 +1,20 @@
 module ActiveJob
   module QueueAdapters
+    # == Active Job Inline adapter
+    #
+    # When enqueueing jobs with the Inline adapter the job will be executed
+    # immediately.
+    #
+    # To use the Inline set the queue_adapter config to +:inline+.
+    #
+    #   Rails.application.config.active_job.queue_adapter = :inline
     class InlineAdapter
       class << self
-        def enqueue(job, *args)
-          job.new.execute(*args)
+        def enqueue(job) #:nodoc:
+          Base.execute(job.serialize)
         end
 
-        def enqueue_at(*)
+        def enqueue_at(*) #:nodoc:
           raise NotImplementedError.new("Use a queueing backend to enqueue jobs in the future. Read more at https://github.com/rails/activejob")
         end
       end

data/lib/active_job/queue_adapters/qu_adapter.rb

@@ -2,27 +2,39 @@ require 'qu'
 
 module ActiveJob
   module QueueAdapters
+    # == Qu adapter for Active Job
+    #
+    # Qu is a Ruby library for queuing and processing background jobs. It is
+    # heavily inspired by delayed_job and Resque. Qu was created to overcome
+    # some shortcomings in the existing queuing libraries that we experienced.
+    # The advantages of Qu are: Multiple backends (redis, mongo), jobs are
+    # requeued when worker is killed, resque-like API.
+    #
+    # Read more about Que {here}[https://github.com/bkeepers/qu].
+    #
+    # To use Qu set the queue_adapter config to +:qu+.
+    #
+    #   Rails.application.config.active_job.queue_adapter = :qu
     class QuAdapter
       class << self
-        def enqueue(job, *args)
-          Qu::Payload.new(klass: JobWrapper, args: [job.name, *args]).tap do |payload|
+        def enqueue(job, *args) #:nodoc:
+          Qu::Payload.new(klass: JobWrapper, args: [job.serialize]).tap do |payload|
             payload.instance_variable_set(:@queue, job.queue_name)
           end.push
         end
 
-        def enqueue_at(job, timestamp, *args)
+        def enqueue_at(job, timestamp, *args) #:nodoc:
           raise NotImplementedError
         end
       end
 
-      class JobWrapper < Qu::Job
-        def initialize(job_name, *args)
-          @job  = job_name.constantize
-          @args = args
+      class JobWrapper < Qu::Job #:nodoc:
+        def initialize(job_data)
+          @job_data  = job_data
         end
 
         def perform
-          @job.new.execute(*@args)
+          Base.execute @job_data
         end
       end
     end

data/lib/active_job/queue_adapters/que_adapter.rb

@@ -2,20 +2,32 @@ require 'que'
 
 module ActiveJob
   module QueueAdapters
+    # == Que adapter for Active Job
+    #
+    # Que is a high-performance alternative to DelayedJob or QueueClassic that
+    # improves the reliability of your application by protecting your jobs with
+    # the same ACID guarantees as the rest of your data. Que is a queue for
+    # Ruby and PostgreSQL that manages jobs using advisory locks.
+    #
+    # Read more about Que {here}[https://github.com/chanks/que].
+    #
+    # To use Que set the queue_adapter config to +:que+.
+    #
+    #   Rails.application.config.active_job.queue_adapter = :que
     class QueAdapter
       class << self
-        def enqueue(job, *args)
-          JobWrapper.enqueue job.name, *args, queue: job.queue_name
+        def enqueue(job) #:nodoc:
+          JobWrapper.enqueue job.serialize, queue: job.queue_name
         end
 
-        def enqueue_at(job, timestamp, *args)
-          raise NotImplementedError
+        def enqueue_at(job, timestamp) #:nodoc:
+          JobWrapper.enqueue job.serialize, queue: job.queue_name, run_at: Time.at(timestamp)
         end
       end
 
-      class JobWrapper < Que::Job
-        def run(job_name, *args)
-          job_name.constantize.new.execute(*args)
+      class JobWrapper < Que::Job #:nodoc:
+        def run(job_data)
+          Base.execute job_data
         end
       end
     end

data/lib/active_job/queue_adapters/queue_classic_adapter.rb

@@ -2,21 +2,50 @@ require 'queue_classic'
 
 module ActiveJob
   module QueueAdapters
+    # == Queue Classic adapter for Active Job
+    #
+    # queue_classic provides a simple interface to a PostgreSQL-backed message
+    # queue. queue_classic specializes in concurrent locking and minimizing
+    # database load while providing a simple, intuitive developer experience.
+    # queue_classic assumes that you are already using PostgreSQL in your
+    # production environment and that adding another dependency (e.g. redis,
+    # beanstalkd, 0mq) is undesirable.
+    #
+    # Read more about Queue Classic {here}[https://github.com/ryandotsmith/queue_classic].
+    #
+    # To use Queue Classic set the queue_adapter config to +:queue_classic+.
+    #
+    #   Rails.application.config.active_job.queue_adapter = :queue_classic
     class QueueClassicAdapter
       class << self
-        def enqueue(job, *args)
-          QC::Queue.new(job.queue_name).enqueue("#{JobWrapper.name}.perform", job.name, *args)
+        def enqueue(job) #:nodoc:
+          build_queue(job.queue_name).enqueue("#{JobWrapper.name}.perform", job.serialize)
         end
 
-        def enqueue_at(job, timestamp, *args)
-          raise NotImplementedError
+        def enqueue_at(job, timestamp) #:nodoc:
+          queue = build_queue(job.queue_name)
+          unless queue.respond_to?(:enqueue_at)
+            raise NotImplementedError, 'To be able to schedule jobs with Queue Classic ' \
+              'the QC::Queue needs to respond to `enqueue_at(timestamp, method, *args)`. '
+              'You can implement this yourself or you can use the queue_classic-later gem.'
+          end
+          queue.enqueue_at(timestamp, "#{JobWrapper.name}.perform", job.serialize)
+        end
+
+        # Builds a <tt>QC::Queue</tt> object to schedule jobs on.
+        #
+        # If you have a custom <tt>QC::Queue</tt> subclass you'll need to suclass
+        # <tt>ActiveJob::QueueAdapters::QueueClassicAdapter</tt> and override the
+        # <tt>build_queue</tt> method.
+        def build_queue(queue_name)
+          QC::Queue.new(queue_name)
         end
       end
 
-      class JobWrapper
+      class JobWrapper #:nodoc:
         class << self
-          def perform(job_name, *args)
-            job_name.constantize.new.execute(*args)
+          def perform(job_data)
+            Base.execute job_data
           end
         end
       end