activejob 4.2.11.3 → 5.0.0.beta1

data/lib/active_job/base.rb

@@ -1,6 +1,7 @@
 require 'active_job/core'
 require 'active_job/queue_adapter'
 require 'active_job/queue_name'
+require 'active_job/queue_priority'
 require 'active_job/enqueuing'
 require 'active_job/execution'
 require 'active_job/callbacks'
@@ -35,7 +36,7 @@ module ActiveJob #:nodoc:
   # Records that are passed in are serialized/deserialized using Global
   # ID. More information can be found in Arguments.
   #
-  # To enqueue a job to be performed as soon the queueing system is free:
+  # To enqueue a job to be performed as soon as the queueing system is free:
   #
   #   ProcessPhotoJob.perform_later(photo)
   #
@@ -57,6 +58,7 @@ module ActiveJob #:nodoc:
     include Core
     include QueueAdapter
     include QueueName
+    include QueuePriority
     include Enqueuing
     include Execution
     include Callbacks

data/lib/active_job/callbacks.rb

@@ -3,8 +3,8 @@ require 'active_support/callbacks'
 module ActiveJob
   # = Active Job Callbacks
   #
-  # Active Job provides hooks during the lifecycle of a job. Callbacks allow you
-  # to trigger logic during the lifecycle of a job. Available callbacks are:
+  # Active Job provides hooks during the life cycle of a job. Callbacks allow you
+  # to trigger logic during the life cycle of a job. Available callbacks are:
   #
   # * <tt>before_enqueue</tt>
   # * <tt>around_enqueue</tt>

data/lib/active_job/core.rb

@@ -1,4 +1,6 @@
 module ActiveJob
+  # Provides general behavior that will be included into every Active Job
+  # object that inherits from ActiveJob::Base.
   module Core
     extend ActiveSupport::Concern
 
@@ -16,6 +18,12 @@ module ActiveJob
       # Queue in which the job will reside.
       attr_writer :queue_name
 
+      # Priority that the job will have (lower is more priority).
+      attr_writer :priority
+
+      # ID optionally provided by adapter
+      attr_accessor :provider_job_id
+
       # I18n.locale to be used during the job.
       attr_accessor :locale
     end
@@ -25,11 +33,8 @@ module ActiveJob
     module ClassMethods
       # Creates a new job instance from a hash created with +serialize+
       def deserialize(job_data)
-        job                      = job_data['job_class'].constantize.new
-        job.job_id               = job_data['job_id']
-        job.queue_name           = job_data['queue_name']
-        job.serialized_arguments = job_data['arguments']
-        job.locale               = job_data['locale'] || I18n.locale
+        job = job_data['job_class'].constantize.new
+        job.deserialize(job_data)
         job
       end
 
@@ -41,6 +46,7 @@ module ActiveJob
       # * <tt>:wait</tt> - Enqueues the job with the specified delay
       # * <tt>:wait_until</tt> - Enqueues the job at the time specified
       # * <tt>:queue</tt> - Enqueues the job on the specified queue
+      # * <tt>:priority</tt> - Enqueues the job with the specified priority
       #
       # ==== Examples
       #
@@ -49,6 +55,7 @@ module ActiveJob
       #    VideoJob.set(wait_until: Time.now.tomorrow).perform_later(Video.last)
       #    VideoJob.set(queue: :some_queue, wait: 5.minutes).perform_later(Video.last)
       #    VideoJob.set(queue: :some_queue, wait_until: Time.now.tomorrow).perform_later(Video.last)
+      #    VideoJob.set(queue: :some_queue, wait: 5.minutes, priority: 10).perform_later(Video.last)
       def set(options={})
         ConfiguredJob.new(self, options)
       end
@@ -60,6 +67,7 @@ module ActiveJob
       @arguments  = arguments
       @job_id     = SecureRandom.uuid
       @queue_name = self.class.queue_name
+      @priority   = self.class.priority
     end
 
     # Returns a hash with the job data that can safely be passed to the
@@ -69,11 +77,40 @@ module ActiveJob
         'job_class'  => self.class.name,
         'job_id'     => job_id,
         'queue_name' => queue_name,
+        'priority'   => priority,
         'arguments'  => serialize_arguments(arguments),
         'locale'     => I18n.locale
       }
     end
 
+    # Attaches the stored job data to the current instance. Receives a hash
+    # returned from +serialize+
+    #
+    # ==== Examples
+    #
+    #    class DeliverWebhookJob < ActiveJob::Base
+    #      def serialize
+    #        super.merge('attempt_number' => (@attempt_number || 0) + 1)
+    #      end
+    #
+    #      def deserialize(job_data)
+    #        super
+    #        @attempt_number = job_data['attempt_number']
+    #      end
+    #
+    #      rescue_from(TimeoutError) do |exception|
+    #        raise exception if @attempt_number > 5
+    #        retry_job(wait: 10)
+    #      end
+    #    end
+    def deserialize(job_data)
+      self.job_id               = job_data['job_id']
+      self.queue_name           = job_data['queue_name']
+      self.priority             = job_data['priority']
+      self.serialized_arguments = job_data['arguments']
+      self.locale               = job_data['locale'] || I18n.locale
+    end
+
     private
       def deserialize_arguments_if_needed
         if defined?(@serialized_arguments) && @serialized_arguments.present?

data/lib/active_job/enqueuing.rb

@@ -1,6 +1,7 @@
 require 'active_job/arguments'
 
 module ActiveJob
+  # Provides behavior for enqueuing and retrying jobs.
   module Enqueuing
     extend ActiveSupport::Concern
 
@@ -31,6 +32,7 @@ module ActiveJob
     # * <tt>:wait</tt> - Enqueues the job with the specified delay
     # * <tt>:wait_until</tt> - Enqueues the job at the time specified
     # * <tt>:queue</tt> - Enqueues the job on the specified queue
+    # * <tt>:priority</tt> - Enqueues the job with the specified priority
     #
     # ==== Examples
     #
@@ -53,6 +55,7 @@ module ActiveJob
     # * <tt>:wait</tt> - Enqueues the job with the specified delay
     # * <tt>:wait_until</tt> - Enqueues the job at the time specified
     # * <tt>:queue</tt> - Enqueues the job on the specified queue
+    # * <tt>:priority</tt> - Enqueues the job with the specified priority
     #
     # ==== Examples
     #
@@ -60,10 +63,12 @@ module ActiveJob
     #    my_job_instance.enqueue wait: 5.minutes
     #    my_job_instance.enqueue queue: :important
     #    my_job_instance.enqueue wait_until: Date.tomorrow.midnight
+    #    my_job_instance.enqueue priority: 10
     def enqueue(options={})
       self.scheduled_at = options[:wait].seconds.from_now.to_f if options[:wait]
       self.scheduled_at = options[:wait_until].to_f if options[:wait_until]
       self.queue_name   = self.class.queue_name_from_part(options[:queue]) if options[:queue]
+      self.priority     = options[:priority].to_i if options[:priority]
       run_callbacks :enqueue do
         if self.scheduled_at
           self.class.queue_adapter.enqueue_at self, self.scheduled_at

data/lib/active_job/gem_version.rb

@@ -5,10 +5,10 @@ module ActiveJob
   end
 
   module VERSION
-    MAJOR = 4
-    MINOR = 2
-    TINY  = 11
-    PRE   = "3"
+    MAJOR = 5
+    MINOR = 0
+    TINY  = 0
+    PRE   = "beta1"
 
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")
   end

data/lib/active_job/logging.rb

@@ -1,3 +1,4 @@
+require 'active_support/core_ext/hash/transform_values'
 require 'active_support/core_ext/string/filters'
 require 'active_support/tagged_logging'
 require 'active_support/logger'
@@ -40,7 +41,7 @@ module ActiveJob
       def tag_logger(*tags)
         if logger.respond_to?(:tagged)
           tags.unshift "ActiveJob" unless logger_tagged_by_active_job?
-          logger.tagged(*tags){ yield }
+          ActiveJob::Base.logger.tagged(*tags){ yield }
         else
           yield
         end
@@ -81,18 +82,31 @@ module ActiveJob
 
       private
         def queue_name(event)
-          event.payload[:adapter].name.demodulize.remove('Adapter') + "(#{event.payload[:job].queue_name})"
+          event.payload[:adapter].class.name.demodulize.remove('Adapter') + "(#{event.payload[:job].queue_name})"
         end
 
         def args_info(job)
           if job.arguments.any?
             ' with arguments: ' +
-              job.arguments.map { |arg| arg.try(:to_global_id).try(:to_s) || arg.inspect }.join(', ')
+              job.arguments.map { |arg| format(arg).inspect }.join(', ')
           else
             ''
           end
         end
 
+        def format(arg)
+          case arg
+          when Hash
+            arg.transform_values { |value| format(value) }
+          when Array
+            arg.map { |value| format(value) }
+          when GlobalID::Identification
+            arg.to_global_id rescue arg
+          else
+            arg
+          end
+        end
+
         def scheduled_at(event)
           Time.at(event.payload[:job].scheduled_at).utc
         end

data/lib/active_job/queue_adapter.rb

@@ -1,35 +1,63 @@
 require 'active_job/queue_adapters/inline_adapter'
+require 'active_support/core_ext/class/attribute'
 require 'active_support/core_ext/string/inflections'
 
 module ActiveJob
-  # The <tt>ActionJob::QueueAdapter</tt> module is used to load the
-  # correct adapter. The default queue adapter is the :inline queue.
+  # The <tt>ActiveJob::QueueAdapter</tt> module is used to load the
+  # correct adapter. The default queue adapter is the +:inline+ queue.
   module QueueAdapter #:nodoc:
     extend ActiveSupport::Concern
 
+    included do
+      class_attribute :_queue_adapter, instance_accessor: false, instance_predicate: false
+      self.queue_adapter = :inline
+    end
+
     # Includes the setter method for changing the active queue adapter.
     module ClassMethods
-      mattr_reader(:queue_adapter) { ActiveJob::QueueAdapters::InlineAdapter }
+      # Returns the backend queue provider. The default queue adapter
+      # is the +:inline+ queue. See QueueAdapters for more information.
+      def queue_adapter
+        _queue_adapter
+      end
 
       # Specify the backend queue provider. The default queue adapter
-      # is the :inline queue. See QueueAdapters for more
+      # is the +:inline+ queue. See QueueAdapters for more
       # information.
-      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)
-          else
-            name_or_adapter if name_or_adapter.respond_to?(:enqueue)
-          end
+      def queue_adapter=(name_or_adapter_or_class)
+        self._queue_adapter = interpret_adapter(name_or_adapter_or_class)
       end
 
       private
-        def load_adapter(name)
-          "ActiveJob::QueueAdapters::#{name.to_s.camelize}Adapter".constantize
+
+      def interpret_adapter(name_or_adapter_or_class)
+        case name_or_adapter_or_class
+        when Symbol, String
+          ActiveJob::QueueAdapters.lookup(name_or_adapter_or_class).new
+        else
+          if queue_adapter?(name_or_adapter_or_class)
+            name_or_adapter_or_class
+          elsif queue_adapter_class?(name_or_adapter_or_class)
+            ActiveSupport::Deprecation.warn "Passing an adapter class is deprecated " \
+              "and will be removed in Rails 5.1. Please pass an adapter name " \
+              "(.queue_adapter = :#{name_or_adapter_or_class.name.demodulize.remove('Adapter').underscore}) " \
+              "or an instance (.queue_adapter = #{name_or_adapter_or_class.name}.new) instead."
+              name_or_adapter_or_class.new
+          else
+            raise ArgumentError
+          end
         end
+      end
+
+      QUEUE_ADAPTER_METHODS = [:enqueue, :enqueue_at].freeze
+
+      def queue_adapter?(object)
+        QUEUE_ADAPTER_METHODS.all? { |meth| object.respond_to?(meth) }
+      end
+
+      def queue_adapter_class?(object)
+        object.is_a?(Class) && QUEUE_ADAPTER_METHODS.all? { |meth| object.public_method_defined?(meth) }
+      end
     end
   end
 end

data/lib/active_job/queue_adapters.rb

@@ -12,6 +12,8 @@ module ActiveJob
   # * {Sidekiq}[http://sidekiq.org]
   # * {Sneakers}[https://github.com/jondot/sneakers]
   # * {Sucker Punch}[https://github.com/brandonhilkert/sucker_punch]
+  # * {Active Job Async Job}[http://api.rubyonrails.org/classes/ActiveJob/QueueAdapters/AsyncAdapter.html]
+  # * {Active Job Inline}[http://api.rubyonrails.org/classes/ActiveJob/QueueAdapters/InlineAdapter.html]
   #
   # === Backends Features
   #
@@ -26,15 +28,86 @@ module ActiveJob
   #   | Sidekiq           | Yes   | Yes    | Yes        | Queue      | No      | Job     |
   #   | Sneakers          | Yes   | Yes    | No         | Queue      | Queue   | No      |
   #   | Sucker Punch      | Yes   | Yes    | No         | No         | No      | No      |
+  #   | Active Job Async  | Yes   | Yes    | Yes        | No         | No      | No      |
   #   | Active Job Inline | No    | Yes    | N/A        | N/A        | N/A     | N/A     |
   #
+  # ==== Async
+  #
+  # Yes: The Queue Adapter runs the jobs in a separate or forked process.
+  #
+  # No: The job is run in the same process.
+  #
+  # ==== Queues
+  #
+  # Yes: Jobs may set which queue they are run in with queue_as or by using the set
+  # method.
+  #
+  # ==== Delayed
+  #
+  # Yes: The adapter will run the job in the future through perform_later.
+  #
+  # (Gem): An additional gem is required to use perform_later with this adapter.
+  #
+  # No: The adapter will run jobs at the next opportunity and cannot use perform_later.
+  #
+  # N/A: The adapter does not support queueing.
+  #
   # NOTE:
   # queue_classic supports job scheduling since version 3.1.
   # For older versions you can use the queue_classic-later gem.
   #
+  # ==== Priorities
+  #
+  # The order in which jobs are processed can be configured differently depending
+  # on the adapter.
+  #
+  # Job: Any class inheriting from the adapter may set the priority on the job
+  # object relative to other jobs.
+  #
+  # Queue: The adapter can set the priority for job queues, when setting a queue
+  # with Active Job this will be respected.
+  #
+  # Yes: Allows the priority to be set on the job object, at the queue level or
+  # as default configuration option.
+  #
+  # No: Does not allow the priority of jobs to be configured.
+  #
+  # N/A: The adapter does not support queueing, and therefore sorting them.
+  #
+  # ==== Timeout
+  #
+  # When a job will stop after the allotted time.
+  #
+  # Job: The timeout can be set for each instance of the job class.
+  #
+  # Queue: The timeout is set for all jobs on the queue.
+  #
+  # Global: The adapter is configured that all jobs have a maximum run time.
+  #
+  # N/A: This adapter does not run in a separate process, and therefore timeout
+  # is unsupported.
+  #
+  # ==== Retries
+  #
+  # Job: The number of retries can be set per instance of the job class.
+  #
+  # Yes: The Number of retries can be configured globally, for each instance or
+  # on the queue. This adapter may also present failed instances of the job class
+  # that can be restarted.
+  #
+  # Global: The adapter has a global number of retries.
+  #
+  # N/A: The adapter does not run in a separate process, and therefore doesn't
+  # support retries.
+  #
+  # === Async and Inline Queue Adapters
+  #
+  # Active Job has two built-in queue adapters intended for development and
+  # testing: +:async+ and +:inline+.
   module QueueAdapters
     extend ActiveSupport::Autoload
 
+    autoload :AsyncAdapter
     autoload :InlineAdapter
     autoload :BackburnerAdapter
     autoload :DelayedJobAdapter
@@ -46,5 +119,18 @@ module ActiveJob
     autoload :SneakersAdapter
     autoload :SuckerPunchAdapter
     autoload :TestAdapter
+
+    ADAPTER = 'Adapter'.freeze
+    private_constant :ADAPTER
+
+    class << self
+      # Returns adapter for specified name.
+      #
+      #   ActiveJob::QueueAdapters.lookup(:sidekiq)
+      #   # => ActiveJob::QueueAdapters::SidekiqAdapter
+      def lookup(name)
+        const_get(name.to_s.camelize << ADAPTER)
+      end
+    end
   end
 end

data/lib/active_job/queue_adapters/async_adapter.rb

@@ -0,0 +1,23 @@
+require 'active_job/async_job'
+
+module ActiveJob
+  module QueueAdapters
+    # == Active Job Async adapter
+    #
+    # When enqueueing jobs with the Async adapter the job will be executed
+    # asynchronously using {AsyncJob}[http://api.rubyonrails.org/classes/ActiveJob/AsyncJob.html].
+    #
+    # To use +AsyncJob+ set the queue_adapter config to +:async+.
+    #
+    #   Rails.application.config.active_job.queue_adapter = :async
+    class AsyncAdapter
+      def enqueue(job) #:nodoc:
+        ActiveJob::AsyncJob.enqueue(job.serialize, queue: job.queue_name)
+      end
+
+      def enqueue_at(job, timestamp) #:nodoc:
+        ActiveJob::AsyncJob.enqueue_at(job.serialize, timestamp, queue: job.queue_name)
+      end
+    end
+  end
+end