From c9a4c2a5ce3eab52e2335362fe643328831a0ac4 Mon Sep 17 00:00:00 2001 From: Cristian Bica Date: Sun, 21 Sep 2014 23:20:23 +0300 Subject: [PATCH] Added RDoc for each Active Job adapter --- activejob/README.md | 19 +++------ activejob/lib/active_job/queue_adapters.rb | 34 +++++++++++++++ .../queue_adapters/backburner_adapter.rb | 14 ++++++- .../queue_adapters/delayed_job_adapter.rb | 14 ++++++- .../queue_adapters/inline_adapter.rb | 12 +++++- .../active_job/queue_adapters/qu_adapter.rb | 17 +++++++- .../active_job/queue_adapters/que_adapter.rb | 16 ++++++- .../queue_adapters/queue_classic_adapter.rb | 18 +++++++- .../queue_adapters/resque_adapter.rb | 15 ++++++- .../queue_adapters/sidekiq_adapter.rb | 16 ++++++- .../queue_adapters/sneakers_adapter.rb | 16 ++++++- .../queue_adapters/sucker_punch_adapter.rb | 19 ++++++++- .../active_job/queue_adapters/test_adapter.rb | 13 +++++- guides/source/active_job_basics.md | 42 ++++--------------- 14 files changed, 194 insertions(+), 71 deletions(-) diff --git a/activejob/README.md b/activejob/README.md index 5734ca413e..b5d27272b1 100644 --- a/activejob/README.md +++ b/activejob/README.md @@ -24,9 +24,9 @@ Set the queue adapter for Active Job: ``` ruby ActiveJob::Base.queue_adapter = :inline # default queue adapter -# Adapters currently supported: :backburner, :delayed_job, :qu, :que, :queue_classic, -# :resque, :sidekiq, :sneakers, :sucker_punch ``` +Note: To learn how to use your preferred queueing backend see its adapter +documentation at ActiveJob::QueueAdapters. Declare a job like so: @@ -88,18 +88,9 @@ by default has been mixed into Active Record classes. ## Supported queueing systems -We currently have adapters for: - -* [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](https://github.com/ryandotsmith/queue_classic) -* [Resque 1.x](https://github.com/resque/resque) -* [Sidekiq](https://github.com/mperham/sidekiq) -* [Sneakers](https://github.com/jondot/sneakers) -* [Sucker Punch](https://github.com/brandonhilkert/sucker_punch) - +Active Job has built-in adapters for multiple queueing backends (Sidekiq, +Resque, Delayed Job and others). To get an up-to-date list of the adapters +see the API Documentation for [ActiveJob::QueueAdapters](http://api.rubyonrails.org/classes/ActiveJob/QueueAdapters.html). ## Auxiliary gems diff --git a/activejob/lib/active_job/queue_adapters.rb b/activejob/lib/active_job/queue_adapters.rb index 345b01ef00..e865c901ce 100644 --- a/activejob/lib/active_job/queue_adapters.rb +++ b/activejob/lib/active_job/queue_adapters.rb @@ -1,4 +1,38 @@ 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 diff --git a/activejob/lib/active_job/queue_adapters/backburner_adapter.rb b/activejob/lib/active_job/queue_adapters/backburner_adapter.rb index a07a6fc223..2453d065de 100644 --- a/activejob/lib/active_job/queue_adapters/backburner_adapter.rb +++ b/activejob/lib/active_job/queue_adapters/backburner_adapter.rb @@ -2,13 +2,23 @@ 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) + def enqueue(job) #:nodoc: Backburner::Worker.enqueue JobWrapper, [ job.serialize ], queue: job.queue_name end - def enqueue_at(job, timestamp) + 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 diff --git a/activejob/lib/active_job/queue_adapters/delayed_job_adapter.rb b/activejob/lib/active_job/queue_adapters/delayed_job_adapter.rb index 30c535f3b4..370a1fc01f 100644 --- a/activejob/lib/active_job/queue_adapters/delayed_job_adapter.rb +++ b/activejob/lib/active_job/queue_adapters/delayed_job_adapter.rb @@ -2,13 +2,23 @@ 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) + def enqueue(job) #:nodoc: JobWrapper.new.delay(queue: job.queue_name).perform(job.serialize) end - def enqueue_at(job, timestamp) + def enqueue_at(job, timestamp) #:nodoc: JobWrapper.new.delay(queue: job.queue_name, run_at: Time.at(timestamp)).perform(job.serialize) end end diff --git a/activejob/lib/active_job/queue_adapters/inline_adapter.rb b/activejob/lib/active_job/queue_adapters/inline_adapter.rb index fdefa38d5e..e498454909 100644 --- a/activejob/lib/active_job/queue_adapters/inline_adapter.rb +++ b/activejob/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) + 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 diff --git a/activejob/lib/active_job/queue_adapters/qu_adapter.rb b/activejob/lib/active_job/queue_adapters/qu_adapter.rb index 5485f20689..7cdefefc02 100644 --- a/activejob/lib/active_job/queue_adapters/qu_adapter.rb +++ b/activejob/lib/active_job/queue_adapters/qu_adapter.rb @@ -2,15 +2,28 @@ 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) + 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 diff --git a/activejob/lib/active_job/queue_adapters/que_adapter.rb b/activejob/lib/active_job/queue_adapters/que_adapter.rb index 2e8a64aa87..e501fe0368 100644 --- a/activejob/lib/active_job/queue_adapters/que_adapter.rb +++ b/activejob/lib/active_job/queue_adapters/que_adapter.rb @@ -2,13 +2,25 @@ 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) + def enqueue(job) #:nodoc: JobWrapper.enqueue job.serialize, queue: job.queue_name end - def enqueue_at(job, timestamp) + def enqueue_at(job, timestamp) #:nodoc: JobWrapper.enqueue job.serialize, queue: job.queue_name, run_at: Time.at(timestamp) end end diff --git a/activejob/lib/active_job/queue_adapters/queue_classic_adapter.rb b/activejob/lib/active_job/queue_adapters/queue_classic_adapter.rb index e8452938b8..bde20e037e 100644 --- a/activejob/lib/active_job/queue_adapters/queue_classic_adapter.rb +++ b/activejob/lib/active_job/queue_adapters/queue_classic_adapter.rb @@ -2,13 +2,27 @@ 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) + def enqueue(job) #:nodoc: build_queue(job.queue_name).enqueue("#{JobWrapper.name}.perform", job.serialize) end - def enqueue_at(job, timestamp) + 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 ' \ diff --git a/activejob/lib/active_job/queue_adapters/resque_adapter.rb b/activejob/lib/active_job/queue_adapters/resque_adapter.rb index b1bc2f15ee..88c6b48fef 100644 --- a/activejob/lib/active_job/queue_adapters/resque_adapter.rb +++ b/activejob/lib/active_job/queue_adapters/resque_adapter.rb @@ -14,13 +14,24 @@ module ActiveJob module QueueAdapters + # == Resque adapter for Active Job + # + # Resque (pronounced like "rescue") is a Redis-backed library for creating + # background jobs, placing those jobs on multiple queues, and processing + # them later. + # + # Read more about Resque {here}[https://github.com/resque/resque]. + # + # To use Resque set the queue_adapter config to +:resque+. + # + # Rails.application.config.active_job.queue_adapter = :resque class ResqueAdapter class << self - def enqueue(job) + def enqueue(job) #:nodoc: Resque.enqueue_to job.queue_name, JobWrapper, job.serialize end - def enqueue_at(job, timestamp) + def enqueue_at(job, timestamp) #:nodoc: unless Resque.respond_to?(:enqueue_at_with_queue) raise NotImplementedError, "To be able to schedule jobs with Resque you need the " \ "resque-scheduler gem. Please add it to your Gemfile and run bundle install" diff --git a/activejob/lib/active_job/queue_adapters/sidekiq_adapter.rb b/activejob/lib/active_job/queue_adapters/sidekiq_adapter.rb index 6d351172de..74655cf0ca 100644 --- a/activejob/lib/active_job/queue_adapters/sidekiq_adapter.rb +++ b/activejob/lib/active_job/queue_adapters/sidekiq_adapter.rb @@ -2,9 +2,21 @@ module ActiveJob module QueueAdapters + # == Sidekiq adapter for Active Job + # + # Simple, efficient background processing for Ruby. Sidekiq uses threads to + # handle many jobs at the same time in the same process. It does not + # require Rails but will integrate tightly with Rails 3/4 to make + # background processing dead simple. + # + # Read more about Sidekiq {here}[http://sidekiq.org]. + # + # To use Sidekiq set the queue_adapter config to +:sidekiq+. + # + # Rails.application.config.active_job.queue_adapter = :sidekiq class SidekiqAdapter class << self - def enqueue(job) + def enqueue(job) #:nodoc: #Sidekiq::Client does not support symbols as keys Sidekiq::Client.push \ 'class' => JobWrapper, @@ -13,7 +25,7 @@ def enqueue(job) 'retry' => true end - def enqueue_at(job, timestamp) + def enqueue_at(job, timestamp) #:nodoc: Sidekiq::Client.push \ 'class' => JobWrapper, 'queue' => job.queue_name, diff --git a/activejob/lib/active_job/queue_adapters/sneakers_adapter.rb b/activejob/lib/active_job/queue_adapters/sneakers_adapter.rb index 91658e08f0..6d60a2f303 100644 --- a/activejob/lib/active_job/queue_adapters/sneakers_adapter.rb +++ b/activejob/lib/active_job/queue_adapters/sneakers_adapter.rb @@ -3,18 +3,30 @@ module ActiveJob module QueueAdapters + # == Sneakers adapter for Active Job + # + # A high-performance RabbitMQ background processing framework for Ruby. + # Sneakers is being used in production for both I/O and CPU intensive + # workloads, and have achieved the goals of high-performance and + # 0-maintenance, as designed. + # + # Read more about Sneakers {here}[https://github.com/jondot/sneakers]. + # + # To use Sneakers set the queue_adapter config to +:sneakers+. + # + # Rails.application.config.active_job.queue_adapter = :sneakers class SneakersAdapter @monitor = Monitor.new class << self - def enqueue(job) + def enqueue(job) #:nodoc: @monitor.synchronize do JobWrapper.from_queue job.queue_name JobWrapper.enqueue ActiveSupport::JSON.encode(job.serialize) end end - def enqueue_at(job, timestamp) + def enqueue_at(job, timestamp) #:nodoc: raise NotImplementedError end end diff --git a/activejob/lib/active_job/queue_adapters/sucker_punch_adapter.rb b/activejob/lib/active_job/queue_adapters/sucker_punch_adapter.rb index 68aa58cadb..be9e7fd03a 100644 --- a/activejob/lib/active_job/queue_adapters/sucker_punch_adapter.rb +++ b/activejob/lib/active_job/queue_adapters/sucker_punch_adapter.rb @@ -2,13 +2,28 @@ module ActiveJob module QueueAdapters + # == Sucker Punch adapter for Active Job + # + # Sucker Punch is a single-process Ruby asynchronous processing library. + # It's girl_friday and DSL sugar on top of Celluloid. With Celluloid's + # actor pattern, we can do asynchronous processing within a single process. + # This reduces costs of hosting on a service like Heroku along with the + # memory footprint of having to maintain additional jobs if hosting on + # a dedicated server. All queues can run within a single Rails/Sinatra + # process. + # + # Read more about Sucker Punch {here}[https://github.com/brandonhilkert/sucker_punch]. + # + # To use Sucker Punch set the queue_adapter config to +:sucker_punch+. + # + # Rails.application.config.active_job.queue_adapter = :sucker_punch class SuckerPunchAdapter class << self - def enqueue(job) + def enqueue(job) #:nodoc: JobWrapper.new.async.perform job.serialize end - def enqueue_at(job, timestamp) + def enqueue_at(job, timestamp) #:nodoc: raise NotImplementedError end end diff --git a/activejob/lib/active_job/queue_adapters/test_adapter.rb b/activejob/lib/active_job/queue_adapters/test_adapter.rb index 12ef72310d..e4fdf60008 100644 --- a/activejob/lib/active_job/queue_adapters/test_adapter.rb +++ b/activejob/lib/active_job/queue_adapters/test_adapter.rb @@ -1,5 +1,14 @@ module ActiveJob module QueueAdapters + # == Test adapter for Active Job + # + # The test adapter should be used only in testing. Along with + # ActiveJob::TestCase and ActiveJob::TestHelper + # it makes a great tool to test your Rails application. + # + # To use the test adapter set queue_adapter config to +:test+. + # + # Rails.application.config.active_job.queue_adapter = :test class TestAdapter delegate :name, to: :class attr_accessor(:perform_enqueued_jobs, :perform_enqueued_at_jobs) @@ -15,7 +24,7 @@ def performed_jobs @performed_jobs ||= [] end - def enqueue(job) + def enqueue(job) #:nodoc: if perform_enqueued_jobs performed_jobs << {job: job.class, args: job.arguments, queue: job.queue_name} job.perform_now @@ -24,7 +33,7 @@ def enqueue(job) end end - def enqueue_at(job, timestamp) + def enqueue_at(job, timestamp) #:nodoc: if perform_enqueued_at_jobs performed_jobs << {job: job.class, args: job.arguments, queue: job.queue_name, at: timestamp} job.perform_now diff --git a/guides/source/active_job_basics.md b/guides/source/active_job_basics.md index f2831defe6..2fd242cb2c 100644 --- a/guides/source/active_job_basics.md +++ b/guides/source/active_job_basics.md @@ -99,41 +99,13 @@ If no adapter is set, the job is immediately executed. ### Backends -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](https://github.com/mperham/sidekiq) -* [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. - -### Change Backends - -You can easily change your adapter: +Active Job has built-in adapters for multiple queueing backends (Sidekiq, +Resque, Delayed Job and others). To get an up-to-date list of the adapters +see the API Documentation for [ActiveJob::QueueAdapters](http://api.rubyonrails.org/classes/ActiveJob/QueueAdapters.html). + +### Changing the Backend + +You can easily change your queueing backend: ```ruby # be sure to have the adapter gem in your Gemfile and follow the adapter specific -- GitLab