1
0
Fork 0
mirror of https://github.com/rails/rails.git synced 2022-11-09 12:12:34 -05:00
rails--rails/activejob/lib/active_job/enqueuing.rb

86 lines
2.8 KiB
Ruby
Raw Normal View History

2017-07-09 13:49:52 -04:00
# frozen_string_literal: true
require "active_job/arguments"
2014-05-19 06:06:09 -04:00
module ActiveJob
# Provides behavior for enqueuing jobs.
Communicate enqueue failures to callers of perform_later There is presently no clean way of telling a caller of `perform_later` the reason why a job failed to enqueue. When the job is enqueued successfully, the job object itself is returned, but when the job can not be enqueued, only `false` is returned. This does not allow callers to distinguish between classes of failures. One important class of failures is when the job backend experiences a network partition when communicating with its underlying datastore. It is entirely possible for that network partition to recover and as such, code attempting to enqueue a job may wish to take action to reenqueue that job after a brief delay. This is distinguished from the class of failures where due a business rule defined in a callback in the application, a job fails to enqueue and should not be retried. This PR changes the following: - Allows a block to be passed to the `perform_later` method. After the `enqueue` method is executed, but before the result is returned, the job will be yielded to the block. This allows the code invoking the `perform_later` method to inspect the job object, even in failure scenarios. - Adds an exception `EnqueueError` which job adapters can raise if they detect a problem specific to their underlying implementation or infrastructure during the enqueue process. - Adds two properties to the job base class: `successfully_enqueued` and `enqueue_error`. `enqueue_error` will be populated by the `enqueue` method if it rescues an `EnqueueError` raised by the job backend. `successfully_enqueued` will be true if the job is not rejected by callbacks and does not cause the job backend to raise an `EnqueueError` and will be `false` otherwise. This will allow developers to do something like the following: MyJob.perform_later do |job| unless job.successfully_enqueued? if job.enqueue_error&.message == "Redis was unavailable" # invoke some code that will retry the job after a delay end end end
2021-01-19 09:57:46 -05:00
# Can be raised by adapters if they wish to communicate to the caller a reason
# why the adapter was unexpectedly unable to enqueue a job.
class EnqueueError < StandardError; end
2014-05-19 06:06:09 -04:00
module Enqueuing
extend ActiveSupport::Concern
2014-05-30 19:19:30 -04:00
# Includes the +perform_later+ method for job initialization.
module ClassMethods
# Push a job onto the queue. By default the arguments must be either String,
# Integer, Float, NilClass, TrueClass, FalseClass, BigDecimal, Symbol, Date,
# Time, DateTime, ActiveSupport::TimeWithZone, ActiveSupport::Duration,
# Hash, ActiveSupport::HashWithIndifferentAccess, Array, Range or
# GlobalID::Identification instances, although this can be extended by adding
# custom serializers.
#
# Returns an instance of the job class queued with arguments available in
Communicate enqueue failures to callers of perform_later There is presently no clean way of telling a caller of `perform_later` the reason why a job failed to enqueue. When the job is enqueued successfully, the job object itself is returned, but when the job can not be enqueued, only `false` is returned. This does not allow callers to distinguish between classes of failures. One important class of failures is when the job backend experiences a network partition when communicating with its underlying datastore. It is entirely possible for that network partition to recover and as such, code attempting to enqueue a job may wish to take action to reenqueue that job after a brief delay. This is distinguished from the class of failures where due a business rule defined in a callback in the application, a job fails to enqueue and should not be retried. This PR changes the following: - Allows a block to be passed to the `perform_later` method. After the `enqueue` method is executed, but before the result is returned, the job will be yielded to the block. This allows the code invoking the `perform_later` method to inspect the job object, even in failure scenarios. - Adds an exception `EnqueueError` which job adapters can raise if they detect a problem specific to their underlying implementation or infrastructure during the enqueue process. - Adds two properties to the job base class: `successfully_enqueued` and `enqueue_error`. `enqueue_error` will be populated by the `enqueue` method if it rescues an `EnqueueError` raised by the job backend. `successfully_enqueued` will be true if the job is not rejected by callbacks and does not cause the job backend to raise an `EnqueueError` and will be `false` otherwise. This will allow developers to do something like the following: MyJob.perform_later do |job| unless job.successfully_enqueued? if job.enqueue_error&.message == "Redis was unavailable" # invoke some code that will retry the job after a delay end end end
2021-01-19 09:57:46 -05:00
# Job#arguments or false if the enqueue did not succeed.
#
# After the attempted enqueue, the job will be yielded to an optional block.
def perform_later(...)
job = job_or_instantiate(...)
Communicate enqueue failures to callers of perform_later There is presently no clean way of telling a caller of `perform_later` the reason why a job failed to enqueue. When the job is enqueued successfully, the job object itself is returned, but when the job can not be enqueued, only `false` is returned. This does not allow callers to distinguish between classes of failures. One important class of failures is when the job backend experiences a network partition when communicating with its underlying datastore. It is entirely possible for that network partition to recover and as such, code attempting to enqueue a job may wish to take action to reenqueue that job after a brief delay. This is distinguished from the class of failures where due a business rule defined in a callback in the application, a job fails to enqueue and should not be retried. This PR changes the following: - Allows a block to be passed to the `perform_later` method. After the `enqueue` method is executed, but before the result is returned, the job will be yielded to the block. This allows the code invoking the `perform_later` method to inspect the job object, even in failure scenarios. - Adds an exception `EnqueueError` which job adapters can raise if they detect a problem specific to their underlying implementation or infrastructure during the enqueue process. - Adds two properties to the job base class: `successfully_enqueued` and `enqueue_error`. `enqueue_error` will be populated by the `enqueue` method if it rescues an `EnqueueError` raised by the job backend. `successfully_enqueued` will be true if the job is not rejected by callbacks and does not cause the job backend to raise an `EnqueueError` and will be `false` otherwise. This will allow developers to do something like the following: MyJob.perform_later do |job| unless job.successfully_enqueued? if job.enqueue_error&.message == "Redis was unavailable" # invoke some code that will retry the job after a delay end end end
2021-01-19 09:57:46 -05:00
enqueue_result = job.enqueue
yield job if block_given?
enqueue_result
end
private
def job_or_instantiate(*args) # :doc:
2014-08-25 10:34:50 -04:00
args.first.is_a?(self) ? args.first : new(*args)
end
ruby2_keywords(:job_or_instantiate)
end
2014-05-30 19:19:30 -04:00
# Enqueues the job to be performed by the queue adapter.
2014-08-25 10:34:50 -04:00
#
# ==== Options
# * <tt>:wait</tt> - Enqueues the job with the specified delay
# * <tt>:wait_until</tt> - Enqueues the job at the time specified
2014-08-25 10:34:50 -04:00
# * <tt>:queue</tt> - Enqueues the job on the specified queue
2015-03-18 05:48:26 -04:00
# * <tt>:priority</tt> - Enqueues the job with the specified priority
2014-08-25 10:34:50 -04:00
#
# ==== Examples
#
# my_job_instance.enqueue
# my_job_instance.enqueue wait: 5.minutes
2014-08-25 10:34:50 -04:00
# my_job_instance.enqueue queue: :important
# my_job_instance.enqueue wait_until: Date.tomorrow.midnight
2015-03-18 05:48:26 -04:00
# 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]
2014-08-25 10:34:50 -04:00
self.queue_name = self.class.queue_name_from_part(options[:queue]) if options[:queue]
2015-03-18 05:48:26 -04:00
self.priority = options[:priority].to_i if options[:priority]
Communicate enqueue failures to callers of perform_later There is presently no clean way of telling a caller of `perform_later` the reason why a job failed to enqueue. When the job is enqueued successfully, the job object itself is returned, but when the job can not be enqueued, only `false` is returned. This does not allow callers to distinguish between classes of failures. One important class of failures is when the job backend experiences a network partition when communicating with its underlying datastore. It is entirely possible for that network partition to recover and as such, code attempting to enqueue a job may wish to take action to reenqueue that job after a brief delay. This is distinguished from the class of failures where due a business rule defined in a callback in the application, a job fails to enqueue and should not be retried. This PR changes the following: - Allows a block to be passed to the `perform_later` method. After the `enqueue` method is executed, but before the result is returned, the job will be yielded to the block. This allows the code invoking the `perform_later` method to inspect the job object, even in failure scenarios. - Adds an exception `EnqueueError` which job adapters can raise if they detect a problem specific to their underlying implementation or infrastructure during the enqueue process. - Adds two properties to the job base class: `successfully_enqueued` and `enqueue_error`. `enqueue_error` will be populated by the `enqueue` method if it rescues an `EnqueueError` raised by the job backend. `successfully_enqueued` will be true if the job is not rejected by callbacks and does not cause the job backend to raise an `EnqueueError` and will be `false` otherwise. This will allow developers to do something like the following: MyJob.perform_later do |job| unless job.successfully_enqueued? if job.enqueue_error&.message == "Redis was unavailable" # invoke some code that will retry the job after a delay end end end
2021-01-19 09:57:46 -05:00
self.successfully_enqueued = false
2014-08-25 10:34:50 -04:00
run_callbacks :enqueue do
if scheduled_at
queue_adapter.enqueue_at self, scheduled_at
2014-08-25 10:34:50 -04:00
else
queue_adapter.enqueue self
2014-08-25 10:34:50 -04:00
end
Communicate enqueue failures to callers of perform_later There is presently no clean way of telling a caller of `perform_later` the reason why a job failed to enqueue. When the job is enqueued successfully, the job object itself is returned, but when the job can not be enqueued, only `false` is returned. This does not allow callers to distinguish between classes of failures. One important class of failures is when the job backend experiences a network partition when communicating with its underlying datastore. It is entirely possible for that network partition to recover and as such, code attempting to enqueue a job may wish to take action to reenqueue that job after a brief delay. This is distinguished from the class of failures where due a business rule defined in a callback in the application, a job fails to enqueue and should not be retried. This PR changes the following: - Allows a block to be passed to the `perform_later` method. After the `enqueue` method is executed, but before the result is returned, the job will be yielded to the block. This allows the code invoking the `perform_later` method to inspect the job object, even in failure scenarios. - Adds an exception `EnqueueError` which job adapters can raise if they detect a problem specific to their underlying implementation or infrastructure during the enqueue process. - Adds two properties to the job base class: `successfully_enqueued` and `enqueue_error`. `enqueue_error` will be populated by the `enqueue` method if it rescues an `EnqueueError` raised by the job backend. `successfully_enqueued` will be true if the job is not rejected by callbacks and does not cause the job backend to raise an `EnqueueError` and will be `false` otherwise. This will allow developers to do something like the following: MyJob.perform_later do |job| unless job.successfully_enqueued? if job.enqueue_error&.message == "Redis was unavailable" # invoke some code that will retry the job after a delay end end end
2021-01-19 09:57:46 -05:00
self.successfully_enqueued = true
rescue EnqueueError => e
self.enqueue_error = e
end
Communicate enqueue failures to callers of perform_later There is presently no clean way of telling a caller of `perform_later` the reason why a job failed to enqueue. When the job is enqueued successfully, the job object itself is returned, but when the job can not be enqueued, only `false` is returned. This does not allow callers to distinguish between classes of failures. One important class of failures is when the job backend experiences a network partition when communicating with its underlying datastore. It is entirely possible for that network partition to recover and as such, code attempting to enqueue a job may wish to take action to reenqueue that job after a brief delay. This is distinguished from the class of failures where due a business rule defined in a callback in the application, a job fails to enqueue and should not be retried. This PR changes the following: - Allows a block to be passed to the `perform_later` method. After the `enqueue` method is executed, but before the result is returned, the job will be yielded to the block. This allows the code invoking the `perform_later` method to inspect the job object, even in failure scenarios. - Adds an exception `EnqueueError` which job adapters can raise if they detect a problem specific to their underlying implementation or infrastructure during the enqueue process. - Adds two properties to the job base class: `successfully_enqueued` and `enqueue_error`. `enqueue_error` will be populated by the `enqueue` method if it rescues an `EnqueueError` raised by the job backend. `successfully_enqueued` will be true if the job is not rejected by callbacks and does not cause the job backend to raise an `EnqueueError` and will be `false` otherwise. This will allow developers to do something like the following: MyJob.perform_later do |job| unless job.successfully_enqueued? if job.enqueue_error&.message == "Redis was unavailable" # invoke some code that will retry the job after a delay end end end
2021-01-19 09:57:46 -05:00
if successfully_enqueued?
self
else
false
2014-08-25 10:34:50 -04:00
end
end
2014-05-19 06:06:09 -04:00
end
2014-05-19 16:13:40 -04:00
end