From 62f9ac033664a738e5c90060b92e71fcb6382480 Mon Sep 17 00:00:00 2001 From: Johnny Shields Date: Sat, 3 Apr 2021 21:34:48 +0900 Subject: [PATCH] More cleanup to README --- README.md | 59 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 33 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index ac6df8b5b..b403554f3 100644 --- a/README.md +++ b/README.md @@ -218,46 +218,46 @@ jobs where a queue is not specified, set a default queue name with ### Running as a Daemon Process -`script/delayed_job` can be used to manage a background process which will -start working off jobs. +`script/delayed_job` starts a background daemon process which will continually work jobs. -To do so, add `gem "daemons"` to your `Gemfile` and run `rails generate delayed_job`. +To install this script, add `gem "daemons"` to your `Gemfile` then run `rails generate delayed_job`. -You can then do the following: +Then run the `start` command: ``` -# Run a single worker process as a daemon +# Run a single worker as a background process RAILS_ENV=production script/delayed_job start -# Run 4 workers in separate processes +# Run 4 workers in separate background child processes RAILS_ENV=production script/delayed_job -n4 start ``` -These commands may be run on any server so long as it has access to your database. Each worker will check the database at least every 5 seconds. ### Stopping and Restarting +You may use `stop` and `restart` commands. These commands wait for each worker +to finish its current job before proceeding. + ``` -# Stop all workers and exit +# Shutdown all workers and exit RAILS_ENV=production script/delayed_job stop -# Stop all workers and start a single new worker process +# Shutdown all workers and start a single new worker process RAILS_ENV=production script/delayed_job restart -# Stop all workers and start 4 new worker processes +# Shutdown all workers and start 4 new worker processes RAILS_ENV=production script/delayed_job -n4 restart ``` -You may also send `SIGTERM` to stop Delayed Job. - You must pass the same arguments to `restart` that you used when calling `start`. +You may also send `SIGTERM` to stop Delayed Job. + ### Worker Queues and Pools ``` # Set the --queues option to work from a particular queue -RAILS_ENV=production script/delayed_job --queues=tracking start RAILS_ENV=production script/delayed_job --queues=mailers,tasks start # Use the --pool option to specify a worker pool. You can use this option multiple @@ -267,7 +267,7 @@ RAILS_ENV=production script/delayed_job --queues=mailers,tasks start RAILS_ENV=production script/delayed_job --pool=tracking --pool=mailers,tasks:2 --pool=*:2 start ``` -### Exit On Complete mode +### Exit On Complete Mode ``` # Run as a daemon and exit after working all available jobs @@ -306,7 +306,9 @@ You should not need to restart Delayed Job each time you update your code. ### Custom Jobs -Jobs are simple ruby objects with a method called perform. Any object which responds to perform can be stuffed into the jobs table. Job objects are serialized to yaml so that they can later be resurrected by the job runner. +Jobs are simple ruby objects with a method called `perform`. +Any object which responds to `perform` can be enqueued into the jobs table. +Job objects are serialized to YAML so that they can later be marshalled by the job runner. ```ruby NewsletterJob = Struct.new(:text, :emails) do @@ -318,7 +320,7 @@ end Delayed::Job.enqueue NewsletterJob.new('lorem ipsum...', Customers.pluck(:email)) ``` -To set a per-job max attempts that overrides the Delayed::Worker.max_attempts you can define a max_attempts method on the job +To override `Delayed::Worker.max_attempts` per-job, you can define a `max_attempts` instance method in the job class. ```ruby NewsletterJob = Struct.new(:text, :emails) do @@ -332,9 +334,11 @@ NewsletterJob = Struct.new(:text, :emails) do end ``` -To set a per-job max run time that overrides the Delayed::Worker.max_run_time you can define a max_run_time method on the job +To override `Delayed::Worker.max_run_time` per-job, you may define a `max_run_time` +instance method in the job class. -NOTE: this can ONLY be used to set a max_run_time that is lower than Delayed::Worker.max_run_time. Otherwise the lock on the job would expire and another worker would start the working on the in progress job. +**NOTE:** You may only set a `max_run_time` that is lower than `Delayed::Worker.max_run_time`. +Otherwise the lock on the job would expire and a second worker would start working the same in-progress job. ```ruby NewsletterJob = Struct.new(:text, :emails) do @@ -348,7 +352,8 @@ NewsletterJob = Struct.new(:text, :emails) do end ``` -To set a per-job default for destroying failed jobs that overrides the Delayed::Worker.destroy_failed_jobs you can define a destroy_failed_jobs? method on the job +To override `Delayed::Worker.destroy_failed_jobs` per-job, you may define a `destroy_failed_jobs?` +instance method in the job class. ```ruby NewsletterJob = Struct.new(:text, :emails) do @@ -362,7 +367,8 @@ NewsletterJob = Struct.new(:text, :emails) do end ``` -To set a default queue name for a custom job that overrides Delayed::Worker.default_queue_name, you can define a queue_name method on the job +To override `Delayed::Worker.default_queue_name` per-job, you may define a `queue_name` +instance method in the job class. ```ruby NewsletterJob = Struct.new(:text, :emails) do @@ -376,7 +382,8 @@ NewsletterJob = Struct.new(:text, :emails) do end ``` -On error, the job is scheduled again in 5 seconds + N ** 4, where N is the number of attempts. You can define your own `reschedule_at` method to override this default behavior. +On error, the job is scheduled again in 5 seconds + N ** 4, where N is the number of attempts. +You may define a `reschedule_at` instance method to override this default behavior. ```ruby NewsletterJob = Struct.new(:text, :emails) do @@ -385,7 +392,7 @@ NewsletterJob = Struct.new(:text, :emails) do end def reschedule_at(current_time, attempts) - current_time + 5.seconds + current_time + (attempts * 60).seconds end end ``` @@ -394,8 +401,8 @@ end You can define hooks on your job that will be called at different stages in the process: -**NOTE:** If you are using ActiveJob these hooks are **not** available to your jobs. -You will need to use ActiveJob's callbacks. +**NOTE:** If you are using Active Job these hooks are **not** available to your jobs. +You will need to use Active Job's callbacks. See the [Rails Guides](https://guides.rubyonrails.org/active_job_basics.html#callbacks) for details. ```ruby @@ -449,7 +456,7 @@ create_table :delayed_jobs, :force => true do |table| end ``` -On error, the job is scheduled again in 5 seconds + N ** 4, where N is the number of attempts or using the job's defined `reschedule_at` method. +On error, the job is scheduled again in 5 seconds + N ** 4, where N is the number of attempts or using the job's defined `reschedule_at` instance method. The default `Delayed::Worker.max_attempts` is 25. After this, the job is either deleted (default), or left in the database with "failed_at" set. With the default of 25 attempts, the last retry will be 20 days later, with the last interval being almost 100 hours. @@ -470,7 +477,7 @@ If no jobs are found, the worker sleeps for the amount of time specified by the It is possible to disable delayed jobs for testing purposes. Set `Delayed::Worker.delay_jobs = false` to execute all jobs realtime. -Or `Delayed::Worker.delay_jobs` can be a Proc that decides whether to execute jobs inline on a per-job basis: +`Delayed::Worker.delay_jobs` may also be a `Proc` that decides whether to execute jobs inline on a per-job basis: ```ruby Delayed::Worker.delay_jobs = ->(job) {