solid_queue 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 553dc884dd38c24c16196da9cceb6e7b40d02bd3f5c005bc980065232b4b1682
-  data.tar.gz: dba6309954b326305526417c05c1a5878a0195d759e8cd6fb6c4453ee61cd6c0
+  metadata.gz: c36dbf886c5dd03f4dab75e6c28b671fbd24ce011589bbab25ef44f640686c96
+  data.tar.gz: de499841947c2a12fa43e0e6e11cf8e8e0789c73ed7290b16ecc32ccfc133283
 SHA512:
-  metadata.gz: dc6ad2d8abd513cd9f357a1190c2173c978b46dd800d1b3f4040364cd70c44b5271da7108901c67a2811586d746607eac4f999c8886a56a1942a228f0f3d1d11
-  data.tar.gz: 999a90c18c09350609670b29bdd3f5e2596815f0a5edb194b225634b9169eca9efaf3e8efda23cfe346e6947e9477b983bbcae1a8a1adf3c6fc2ae9affd4e2ff
+  metadata.gz: 07b6b3b7c8a24aafe97b0b02acebd8fb06f2171dbdb41d6d5c779b70422c633df10850fd8dd569e0fc06a99d8ce4a5ecef21a17f0675fb547c3d5495f142473b
+  data.tar.gz: 4b8e7fbebd2a03c2fa25d498146d469dda245c9a2a979bb604257e2519d101e6a5e36c85479c7d1b3cafbdb3fbad6d0b8d564061868445a85fa1a361cad0dd70

data/README.md

@@ -6,6 +6,31 @@ Besides regular job enqueuing and processing, Solid Queue supports delayed jobs,
 
 Solid Queue can be used with SQL databases such as MySQL, PostgreSQL or SQLite, and it leverages the `FOR UPDATE SKIP LOCKED` clause, if available, to avoid blocking and waiting on locks when polling jobs. It relies on Active Job for retries, discarding, error handling, serialization, or delays, and it's compatible with Ruby on Rails's multi-threading.
 
+## Table of contents
+
+- [Installation](#installation)
+  - [Single database configuration](#single-database-configuration)
+  - [Incremental adoption](#incremental-adoption)
+  - [High performance requirements](#high-performance-requirements)
+- [Configuration](#configuration)
+  - [Workers, dispatchers and scheduler](#workers-dispatchers-and-scheduler)
+  - [Queue order and priorities](#queue-order-and-priorities)
+  - [Queues specification and performance](#queues-specification-and-performance)
+  - [Threads, processes and signals](#threads-processes-and-signals)
+  - [Database configuration](#database-configuration)
+  - [Other configuration settings](#other-configuration-settings)
+- [Lifecycle hooks](#lifecycle-hooks)
+- [Errors when enqueuing](#errors-when-enqueuing)
+- [Concurrency controls](#concurrency-controls)
+- [Failed jobs and retries](#failed-jobs-and-retries)
+  - [Error reporting on jobs](#error-reporting-on-jobs)
+- [Puma plugin](#puma-plugin)
+- [Jobs and transactional integrity](#jobs-and-transactional-integrity)
+- [Recurring tasks](#recurring-tasks)
+- [Inspiration](#inspiration)
+- [License](#license)
+
+
 ## Installation
 
 Solid Queue is configured by default in new Rails 8 applications. But if you're running an earlier version, you can add it manually following these steps:
@@ -43,8 +68,6 @@ production:
     migrations_paths: db/queue_migrate
 ```
 
-Note: Calling `bin/rails solid_queue:install` will automatically add `config.solid_queue.connects_to = { database: { writing: :queue } }` to `config/environments/production.rb`, so no additional configuration is needed there (although you must make sure that you use the `queue` name in `database.yml` for this to match!). But if you want to use Solid Queue in a different environment (like staging or even development), you'll have to manually add that `config.solid_queue.connects_to` line to the respective environment file. And, as always, make sure that the name you're using for the database in `config/database.yml` matches the name you use in `config.solid_queue.connects_to`.
-
 Then run `db:prepare` in production to ensure the database is created and the schema is loaded.
 
 Now you're ready to start processing jobs by running `bin/jobs` on the server that's doing the work. This will start processing jobs in all queues using the default configuration. See [below](#configuration) to learn more about configuring Solid Queue.
@@ -53,6 +76,72 @@ For small projects, you can run Solid Queue on the same machine as your webserve
 
 **Note**: future changes to the schema will come in the form of regular migrations.
 
+### Usage in development and other non-production environments
+
+Calling `bin/rails solid_queue:install` will automatically add `config.solid_queue.connects_to = { database: { writing: :queue } }` to `config/environments/production.rb`. In order to use Solid Queue in other environments (such as development or staging), you'll need to add a similar configuration(s).
+
+For example, if you're using SQLite in development, update `database.yml` as follows:
+
+```diff
+development:
+  primary:
+    <<: *default
+    database: storage/development.sqlite3
++  queue:
++    <<: *default
++    database: storage/development_queue.sqlite3
++    migrations_paths: db/queue_migrate
+```
+
+Next, add the following to `development.rb`
+
+```ruby
+  # Use Solid Queue in Development.
+  config.active_job.queue_adapter = :solid_queue
+  config.solid_queue.connects_to = { database: { writing: :queue } }
+```
+
+Once you've added this, run `db:prepare` to create the Solid Queue database and load the schema.
+
+Finally, in order for jobs to be processed, you'll need to have Solid Queue running. In Development, this can be done via [the Puma plugin](#puma-plugin) as well. In `puma.rb` update the following line:
+
+```ruby
+# You can either set the env var, or check for development
+plugin :solid_queue if ENV["SOLID_QUEUE_IN_PUMA"] || Rails.env.development?
+```
+
+You can also just use `bin/jobs`, but in this case you might want to [set a different logger for Solid Queue](#other-configuration-settings) because the default logger will log to `log/development.log` and you won't see anything when you run `bin/jobs`. For example:
+```ruby
+config.solid_queue.logger = ActiveSupport::Logger.new(STDOUT)
+```
+
+**Note about Action Cable**: If you use Action Cable (or anything dependent on Action Cable, such as Turbo Streams), you will also need to update it to use a database.
+
+In `config/cable.yml`
+
+```diff
+development:
+-  adapter: async
++ adapter: solid_cable
++  connects_to:
++    database:
++      writing: cable
++  polling_interval: 0.1.seconds
++  message_retention: 1.day
+```
+
+In `config/database.yml`
+
+```diff
+development:
+  primary:
+    <<: *default
+    database: storage/development.sqlite3
++  cable:
++    <<: *default
++    database: storage/development_cable.sqlite3
++    migrations_paths: db/cable_migrate
+```
 
 ### Single database configuration
 
@@ -64,7 +153,7 @@ Running Solid Queue in a separate database is recommended, but it's also possibl
 
 You won't have multiple databases, so `database.yml` doesn't need to have primary and queue database.
 
-## Incremental adoption
+### Incremental adoption
 
 If you're planning to adopt Solid Queue incrementally by switching one job at the time, you can do so by leaving the `config.active_job.queue_adapter` set to your old backend, and then set the `queue_adapter` directly in the jobs you're moving:
 
@@ -77,7 +166,7 @@ class MyJob < ApplicationJob
 end
 ```
 
-## High performance requirements
+### High performance requirements
 
 Solid Queue was designed for the highest throughput when used with MySQL 8+ or PostgreSQL 9.5+, as they support `FOR UPDATE SKIP LOCKED`. You can use it with older versions, but in that case, you might run into lock waits if you run multiple workers for the same queue. You can also use it with SQLite on smaller applications.
 
@@ -86,6 +175,7 @@ Solid Queue was designed for the highest throughput when used with MySQL 8+ or P
 ### Workers, dispatchers and scheduler
 
 We have several types of actors in Solid Queue:
+
 - _Workers_ are in charge of picking jobs ready to run from queues and processing them. They work off the `solid_queue_ready_executions` table.
 - _Dispatchers_ are in charge of selecting jobs scheduled to run in the future that are due and _dispatching_ them, which is simply moving them from the `solid_queue_scheduled_executions` table over to the `solid_queue_ready_executions` table so that workers can pick them up. On top of that, they do some maintenance work related to [concurrency controls](#concurrency-controls).
 - The _scheduler_ manages [recurring tasks](#recurring-tasks), enqueuing jobs for them when they're due.
@@ -99,7 +189,6 @@ By default, Solid Queue will try to find your configuration under `config/queue.
 bin/jobs -c config/calendar.yml
 ```
 
-
 This is what this configuration looks like:
 
 ```yml
@@ -149,7 +238,11 @@ Here's an overview of the different options:
   This will create a worker fetching jobs from all queues starting with `staging`. The wildcard `*` is only allowed on its own or at the end of a queue name; you can't specify queue names such as `*_some_queue`. These will be ignored.
 
   Finally, you can combine prefixes with exact names, like `[ staging*, background ]`, and the behaviour with respect to order will be the same as with only exact names.
+
+  Check the sections below on [how queue order behaves combined with priorities](#queue-order-and-priorities), and [how the way you specify the queues per worker might affect performance](#queues-specification-and-performance).
+
 - `threads`: this is the max size of the thread pool that each worker will have to run jobs. Each worker will fetch this number of jobs from their queue(s), at most and will post them to the thread pool to be run. By default, this is `3`. Only workers have this setting.
+It is recommended to set this value less than or equal to the queue database's connection pool size minus 2, as each worker thread uses one connection, and two additional connections are reserved for polling and heartbeat.
 - `processes`: this is the number of worker processes that will be forked by the supervisor with the settings given. By default, this is `1`, just a single process. This setting is useful if you want to dedicate more than one CPU core to a queue or queues with the same configuration. Only workers have this setting.
 - `concurrency_maintenance`: whether the dispatcher will perform the concurrency maintenance work. This is `true` by default, and it's useful if you don't use any [concurrency controls](#concurrency-controls) and want to disable it or if you run multiple dispatchers and want some of them to just dispatch jobs without doing anything else.
 
@@ -164,6 +257,67 @@ This is useful when you run jobs with different importance or urgency in the sam
 
 We recommend not mixing queue order with priorities but either choosing one or the other, as that will make job execution order more straightforward for you.
 
+### Queues specification and performance
+
+To keep polling performant and ensure a covering index is always used, Solid Queue only does two types of polling queries:
+```sql
+-- No filtering by queue
+SELECT job_id
+FROM solid_queue_ready_executions
+ORDER BY priority ASC, job_id ASC
+LIMIT ?
+FOR UPDATE SKIP LOCKED;
+
+-- Filtering by a single queue
+SELECT job_id
+FROM solid_queue_ready_executions
+WHERE queue_name = ?
+ORDER BY priority ASC, job_id ASC
+LIMIT ?
+FOR UPDATE SKIP LOCKED;
+```
+
+The first one (no filtering by queue) is used when you specify
+```yml
+queues: *
+```
+and there aren't any queues paused, as we want to target all queues.
+
+In other cases, we need to have a list of queues to filter by, in order, because we can only filter by a single queue at a time to ensure we use an index to sort. This means that if you specify your queues as:
+```yml
+queues: beta*
+```
+
+we'll need to get a list of all existing queues matching that prefix first, with a query that would look like this:
+```sql
+SELECT DISTINCT(queue_name)
+FROM solid_queue_ready_executions
+WHERE queue_name LIKE 'beta%';
+```
+
+This type of `DISTINCT` query on a column that's the leftmost column in an index can be performed very fast in MySQL thanks to a technique called [Loose Index Scan](https://dev.mysql.com/doc/refman/8.0/en/group-by-optimization.html#loose-index-scan). PostgreSQL and SQLite, however, don't implement this technique, which means that if your `solid_queue_ready_executions` table is very big because your queues get very deep, this query will get slow. Normally your `solid_queue_ready_executions` table will be small, but it can happen.
+
+Similarly to using prefixes, the same will happen if you have paused queues, because we need to get a list of all queues with a query like
+```sql
+SELECT DISTINCT(queue_name)
+FROM solid_queue_ready_executions
+```
+
+and then remove the paused ones. Pausing in general should be something rare, used in special circumstances, and for a short period of time. If you don't want to process jobs from a queue anymore, the best way to do that is to remove it from your list of queues.
+
+💡 To sum up, **if you want to ensure optimal performance on polling**, the best way to do that is to always specify exact names for them, and not have any queues paused.
+
+Do this:
+
+```yml
+queues: background, backend
+```
+
+instead of this:
+```yml
+queues: back*
+```
+
 
 ### Threads, processes and signals
 
@@ -175,7 +329,9 @@ The supervisor is in charge of managing these processes, and it responds to the
 
 When receiving a `QUIT` signal, if workers still have jobs in-flight, these will be returned to the queue when the processes are deregistered.
 
-If processes have no chance of cleaning up before exiting (e.g. if someone pulls a cable somewhere), in-flight jobs might remain claimed by the processes executing them. Processes send heartbeats, and the supervisor checks and prunes processes with expired heartbeats, which will release any claimed jobs back to their queues. You can configure both the frequency of heartbeats and the threshold to consider a process dead. See the section below for this.
+If processes have no chance of cleaning up before exiting (e.g. if someone pulls a cable somewhere), in-flight jobs might remain claimed by the processes executing them. Processes send heartbeats, and the supervisor checks and prunes processes with expired heartbeats. Jobs that were claimed by processes with an expired heartbeat will be marked as failed with a `SolidQueue::Processes::ProcessPrunedError`. You can configure both the frequency of heartbeats and the threshold to consider a process dead. See the section below for this.
+
+In a similar way, if a worker is terminated in any other way not initiated by the above signals (e.g. a worker is sent a `KILL` signal), jobs in progress will be marked as failed so that they can be inspected, with a `SolidQueue::Processes::Process::ProcessExitError`. Sometimes a job in particular is responsible for this, for example, if it has a memory leak and you have a mechanism to kill processes over a certain memory threshold, so this will help identifying this kind of situation.
 
 
 ### Database configuration
@@ -184,6 +340,32 @@ You can configure the database used by Solid Queue via the `config.solid_queue.c
 
 All the options available to Active Record for multiple databases can be used here.
 
+### Other configuration settings
+
+_Note_: The settings in this section should be set in your `config/application.rb` or your environment config like this: `config.solid_queue.silence_polling = true`
+
+There are several settings that control how Solid Queue works that you can set as well:
+- `logger`: the logger you want Solid Queue to use. Defaults to the app logger.
+- `app_executor`: the [Rails executor](https://guides.rubyonrails.org/threading_and_code_execution.html#executor) used to wrap asynchronous operations, defaults to the app executor
+- `on_thread_error`: custom lambda/Proc to call when there's an error within a Solid Queue thread that takes the exception raised as argument. Defaults to
+
+  ```ruby
+  -> (exception) { Rails.error.report(exception, handled: false) }
+  ```
+
+  **This is not used for errors raised within a job execution**. Errors happening in jobs are handled by Active Job's `retry_on` or `discard_on`, and ultimately will result in [failed jobs](#failed-jobs-and-retries). This is for errors happening within Solid Queue itself.
+
+- `use_skip_locked`: whether to use `FOR UPDATE SKIP LOCKED` when performing locking reads. This will be automatically detected in the future, and for now, you'd only need to set this to `false` if your database doesn't support it. For MySQL, that'd be versions < 8, and for PostgreSQL, versions < 9.5. If you use SQLite, this has no effect, as writes are sequential.
+- `process_heartbeat_interval`: the heartbeat interval that all processes will follow—defaults to 60 seconds.
+- `process_alive_threshold`: how long to wait until a process is considered dead after its last heartbeat—defaults to 5 minutes.
+- `shutdown_timeout`: time the supervisor will wait since it sent the `TERM` signal to its supervised processes before sending a `QUIT` version to them requesting immediate termination—defaults to 5 seconds.
+- `silence_polling`: whether to silence Active Record logs emitted when polling for both workers and dispatchers—defaults to `true`.
+- `supervisor_pidfile`: path to a pidfile that the supervisor will create when booting to prevent running more than one supervisor in the same host, or in case you want to use it for a health check. It's `nil` by default.
+- `preserve_finished_jobs`: whether to keep finished jobs in the `solid_queue_jobs` table—defaults to `true`.
+- `clear_finished_jobs_after`: period to keep finished jobs around, in case `preserve_finished_jobs` is true—defaults to 1 day. **Note:** Right now, there's no automatic cleanup of finished jobs. You'd need to do this by periodically invoking `SolidQueue::Job.clear_finished_in_batches`, which can be configured as [a recurring task](#recurring-tasks).
+- `default_concurrency_control_period`: the value to be used as the default for the `duration` parameter in [concurrency controls](#concurrency-controls). It defaults to 3 minutes.
+
+
 ## Lifecycle hooks
 
 In Solid queue, you can hook into two different points in the supervisor's life:
@@ -211,30 +393,6 @@ SolidQueue.on_stop { stop_metrics_server }
 
 These can be called several times to add multiple hooks, but it needs to happen before Solid Queue is started. An initializer would be a good place to do this.
 
-### Other configuration settings
-
-_Note_: The settings in this section should be set in your `config/application.rb` or your environment config like this: `config.solid_queue.silence_polling = true`
-
-There are several settings that control how Solid Queue works that you can set as well:
-- `logger`: the logger you want Solid Queue to use. Defaults to the app logger.
-- `app_executor`: the [Rails executor](https://guides.rubyonrails.org/threading_and_code_execution.html#executor) used to wrap asynchronous operations, defaults to the app executor
-- `on_thread_error`: custom lambda/Proc to call when there's an error within a Solid Queue thread that takes the exception raised as argument. Defaults to
-
-  ```ruby
-  -> (exception) { Rails.error.report(exception, handled: false) }
-  ```
-
-  **This is not used for errors raised within a job execution**. Errors happening in jobs are handled by Active Job's `retry_on` or `discard_on`, and ultimately will result in [failed jobs](#failed-jobs-and-retries). This is for errors happening within Solid Queue itself.
-
-- `use_skip_locked`: whether to use `FOR UPDATE SKIP LOCKED` when performing locking reads. This will be automatically detected in the future, and for now, you'd only need to set this to `false` if your database doesn't support it. For MySQL, that'd be versions < 8, and for PostgreSQL, versions < 9.5. If you use SQLite, this has no effect, as writes are sequential.
-- `process_heartbeat_interval`: the heartbeat interval that all processes will follow—defaults to 60 seconds.
-- `process_alive_threshold`: how long to wait until a process is considered dead after its last heartbeat—defaults to 5 minutes.
-- `shutdown_timeout`: time the supervisor will wait since it sent the `TERM` signal to its supervised processes before sending a `QUIT` version to them requesting immediate termination—defaults to 5 seconds.
-- `silence_polling`: whether to silence Active Record logs emitted when polling for both workers and dispatchers—defaults to `true`.
-- `supervisor_pidfile`: path to a pidfile that the supervisor will create when booting to prevent running more than one supervisor in the same host, or in case you want to use it for a health check. It's `nil` by default.
-- `preserve_finished_jobs`: whether to keep finished jobs in the `solid_queue_jobs` table—defaults to `true`.
-- `clear_finished_jobs_after`: period to keep finished jobs around, in case `preserve_finished_jobs` is true—defaults to 1 day. **Note:** Right now, there's no automatic cleanup of finished jobs. You'd need to do this by periodically invoking `SolidQueue::Job.clear_finished_in_batches`, but this will happen automatically in the near future.
-- `default_concurrency_control_period`: the value to be used as the default for the `duration` parameter in [concurrency controls](#concurrency-controls). It defaults to 3 minutes.
 
 ## Errors when enqueuing
 
@@ -346,15 +504,27 @@ plugin :solid_queue
 ```
 to your `puma.rb` configuration.
 
+If you're using Puma in development but you don't want to use Solid Queue in development, make sure you avoid the plugin being used, for example using an environment variable like this:
+```ruby
+plugin :solid_queue if ENV["SOLID_QUEUE_IN_PUMA"]
+```
+that you set in production only. This is what Rails 8's default Puma config looks like. Otherwise, if you're using Puma in development but not Solid Queue, starting Puma would start also Solid Queue supervisor and it'll most likely fail because it won't be properly configured.
+
 
 ## Jobs and transactional integrity
-:warning: Having your jobs in the same ACID-compliant database as your application data enables a powerful yet sharp tool: taking advantage of transactional integrity to ensure some action in your app is not committed unless your job is also committed and viceversa, and ensuring that your job won't be enqueued until the transaction within which you're enqueing it is committed. This can be very powerful and useful, but it can also backfire if you base some of your logic on this behaviour, and in the future, you move to another active job backend, or if you simply move Solid Queue to its own database, and suddenly the behaviour changes under you.
+:warning: Having your jobs in the same ACID-compliant database as your application data enables a powerful yet sharp tool: taking advantage of transactional integrity to ensure some action in your app is not committed unless your job is also committed and vice versa, and ensuring that your job won't be enqueued until the transaction within which you're enqueuing it is committed. This can be very powerful and useful, but it can also backfire if you base some of your logic on this behaviour, and in the future, you move to another active job backend, or if you simply move Solid Queue to its own database, and suddenly the behaviour changes under you. Because this can be quite tricky and many people shouldn't need to worry about it, by default Solid Queue is configured in a different database as the main app.
+
+Starting from Rails 8, an option which doesn't rely on this transactional integrity and which Active Job provides is to defer the enqueueing of a job inside an Active Record transaction until that transaction successfully commits. This option can be set via the [`enqueue_after_transaction_commit`](https://edgeapi.rubyonrails.org/classes/ActiveJob/Enqueuing.html#method-c-enqueue_after_transaction_commit) class method on the job level and is by default disabled. Either it can be enabled for individual jobs or for all jobs through `ApplicationJob`:
 
-Because this can be quite tricky and many people shouldn't need to worry about it, by default Solid Queue is configured in a different database as the main app, **job enqueuing is deferred until any ongoing transaction is committed** thanks to Active Job's built-in capability to do this. This means that even if you run Solid Queue in the same DB as your app, you won't be taking advantage of this transactional integrity.
+```ruby
+class ApplicationJob < ActiveJob::Base
+  self.enqueue_after_transaction_commit = true
+end
+```
 
-If you prefer to change this, you can set [`config.active_job.enqueue_after_transaction_commit`](https://edgeguides.rubyonrails.org/configuring.html#config-active-job-enqueue-after-transaction-commit) to `never`. You can also set this on a per-job basis.
+Using this option, you can also use Solid Queue in the same database as your app but not rely on transactional integrity.
 
-If you set that to `never` but still want to make sure you're not inadvertently on transactional integrity, you can make sure that:
+If you don't set this option but still want to make sure you're not inadvertently on transactional integrity, you can make sure that:
 - Your jobs relying on specific data are always enqueued on [`after_commit` callbacks](https://guides.rubyonrails.org/active_record_callbacks.html#after-commit-and-after-rollback) or otherwise from a place where you're certain that whatever data the job will use has been committed to the database before the job is enqueued.
 - Or, you configure a different database for Solid Queue, even if it's the same as your app, ensuring that a different connection on the thread handling requests or running jobs for your app will be used to enqueue jobs. For example:
 
@@ -369,6 +539,7 @@ If you set that to `never` but still want to make sure you're not inadvertently
   config.solid_queue.connects_to = { database: { writing: :primary, reading: :replica } }
   ```
 
+
 ## Recurring tasks
 
 Solid Queue supports defining recurring tasks that run at specific times in the future, on a regular basis like cron jobs. These are managed by the scheduler process and are defined in their own configuration file. By default, the file is located in `config/recurring.yml`, but you can set a different path using the environment variable `SOLID_QUEUE_RECURRING_SCHEDULE` or by using the `--recurring_schedule_file` option with `bin/jobs`, like this:
@@ -404,9 +575,15 @@ MyJob.perform_later(42, status: "custom_status")
 
 - `priority`: a numeric priority value to be used when enqueuing the job.
 
-
 Tasks are enqueued at their corresponding times by the scheduler, and each task schedules the next one. This is pretty much [inspired by what GoodJob does](https://github.com/bensheldon/good_job/blob/994ecff5323bf0337e10464841128fda100750e6/lib/good_job/cron_manager.rb).
 
+For recurring tasks defined as a `command`, you can also change the job class that runs them as follows:
+```ruby
+Rails.application.config.after_initialize do # or to_prepare
+  SolidQueue::RecurringTask.default_job_class = MyRecurringCommandJob
+end
+```
+
 It's possible to run multiple schedulers with the same `recurring_tasks` configuration, for example, if you have multiple servers for redundancy, and you run the `scheduler` in more than one of them. To avoid enqueuing duplicate tasks at the same time, an entry in a new `solid_queue_recurring_executions` table is created in the same transaction as the job is enqueued. This table has a unique index on `task_key` and `run_at`, ensuring only one entry per task per time will be created. This only works if you have `preserve_finished_jobs` set to `true` (the default), and the guarantee applies as long as you keep the jobs around.
 
 **Note**: a single recurring schedule is supported, so you can have multiple schedulers using the same schedule, but not multiple schedulers using different configurations.

data/app/models/solid_queue/claimed_execution.rb

@@ -64,6 +64,7 @@ class SolidQueue::ClaimedExecution < SolidQueue::Execution
       finished
     else
       failed_with(result.error)
+      raise result.error
     end
   ensure
     job.unblock_next_blocked_job

data/app/models/solid_queue/job/clearable.rb

@@ -10,9 +10,10 @@ module SolidQueue
       end
 
       class_methods do
-        def clear_finished_in_batches(batch_size: 500, finished_before: SolidQueue.clear_finished_jobs_after.ago, class_name: nil)
+        def clear_finished_in_batches(batch_size: 500, finished_before: SolidQueue.clear_finished_jobs_after.ago, class_name: nil, sleep_between_batches: 0)
           loop do
             records_deleted = clearable(finished_before: finished_before, class_name: class_name).limit(batch_size).delete_all
+            sleep(sleep_between_batches) if sleep_between_batches > 0
             break if records_deleted == 0
           end
         end

data/app/models/solid_queue/queue.rb

@@ -40,6 +40,19 @@ module SolidQueue
       @size ||= ReadyExecution.queued_as(name).count
     end
 
+    def latency
+      @latency ||= begin
+        now = Time.current
+        oldest_enqueued_at = ReadyExecution.queued_as(name).minimum(:created_at) || now
+
+        (now - oldest_enqueued_at).to_i
+      end
+    end
+
+    def human_latency
+      ActiveSupport::Duration.build(latency).inspect
+    end
+
     def ==(queue)
       name == queue.name
     end

data/app/models/solid_queue/queue_selector.rb

@@ -34,7 +34,7 @@ module SolidQueue
       def eligible_queues
         if include_all_queues? then all_queues
         else
-          exact_names + prefixed_names
+          in_raw_order(exact_names + prefixed_names)
         end
       end
 
@@ -42,8 +42,12 @@ module SolidQueue
         "*".in? raw_queues
       end
 
+      def all_queues
+        relation.distinct(:queue_name).pluck(:queue_name)
+      end
+
       def exact_names
-        raw_queues.select { |queue| !queue.include?("*") }
+        raw_queues.select { |queue| exact_name?(queue) }
       end
 
       def prefixed_names
@@ -54,15 +58,41 @@ module SolidQueue
       end
 
       def prefixes
-        @prefixes ||= raw_queues.select { |queue| queue.ends_with?("*") }.map { |queue| queue.tr("*", "%") }
+        @prefixes ||= raw_queues.select { |queue| prefixed_name?(queue) }.map { |queue| queue.tr("*", "%") }
       end
 
-      def all_queues
-        relation.distinct(:queue_name).pluck(:queue_name)
+      def exact_name?(queue)
+        !queue.include?("*")
+      end
+
+      def prefixed_name?(queue)
+        queue.ends_with?("*")
       end
 
       def paused_queues
         @paused_queues ||= Pause.all.pluck(:queue_name)
       end
+
+      def in_raw_order(queues)
+        # Only need to sort if we have prefixes and more than one queue name.
+        # Exact names are selected in the same order as they're found
+        if queues.one? || prefixes.empty?
+          queues
+        else
+          queues = queues.dup
+          raw_queues.flat_map { |raw_queue| delete_in_order(raw_queue, queues) }.compact
+        end
+      end
+
+      def delete_in_order(raw_queue, queues)
+        if exact_name?(raw_queue)
+          queues.delete(raw_queue)
+        elsif prefixed_name?(raw_queue)
+          prefix = raw_queue.tr("*", "")
+          queues.select { |queue| queue.start_with?(prefix) }.tap do |matches|
+            queues -= matches
+          end
+        end
+      end
   end
 end

data/app/models/solid_queue/record.rb

@@ -4,7 +4,7 @@ module SolidQueue
   class Record < ActiveRecord::Base
     self.abstract_class = true
 
-    connects_to **SolidQueue.connects_to if SolidQueue.connects_to
+    connects_to(**SolidQueue.connects_to) if SolidQueue.connects_to
 
     def self.non_blocking_lock
       if SolidQueue.use_skip_locked

data/app/models/solid_queue/recurring_task.rb

@@ -12,6 +12,8 @@ module SolidQueue
 
     scope :static, -> { where(static: true) }
 
+    has_many :recurring_executions, foreign_key: :task_key, primary_key: :key
+
     mattr_accessor :default_job_class
     self.default_job_class = RecurringJob
 
@@ -53,6 +55,18 @@ module SolidQueue
       parsed_schedule.next_time.utc
     end
 
+    def previous_time
+      parsed_schedule.previous_time.utc
+    end
+
+    def last_enqueued_time
+      if recurring_executions.loaded?
+        recurring_executions.map(&:run_at).max
+      else
+        recurring_executions.maximum(:run_at)
+      end
+    end
+
     def enqueue(at:)
       SolidQueue.instrument(:enqueue_recurring_task, task: key, at: at) do |payload|
         active_job = if using_solid_queue_adapter?
@@ -67,11 +81,15 @@ module SolidQueue
           end
         end
 
-        payload[:active_job_id] = active_job.job_id if active_job
+        active_job.tap do |enqueued_job|
+          payload[:active_job_id] = enqueued_job.job_id
+        end
       rescue RecurringExecution::AlreadyRecorded
         payload[:skipped] = true
+        false
       rescue Job::EnqueueError => error
         payload[:enqueue_error] = error.message
+        false
       end
     end
 

data/lib/generators/solid_queue/install/install_generator.rb

@@ -11,9 +11,11 @@ class SolidQueue::InstallGenerator < Rails::Generators::Base
     chmod "bin/jobs", 0755 & ~File.umask, verbose: false
   end
 
-  def configure_active_job_adapter
-    gsub_file Pathname(destination_root).join("config/environments/production.rb"),
-      /(# )?config\.active_job\.queue_adapter\s+=.*/,
+  def configure_adapter_and_database
+    pathname = Pathname(destination_root).join("config/environments/production.rb")
+
+    gsub_file pathname, /\n\s*config\.solid_queue\.connects_to\s+=.*\n/, "\n", verbose: false
+    gsub_file pathname, /(# )?config\.active_job\.queue_adapter\s+=.*\n/,
       "config.active_job.queue_adapter = :solid_queue\n" +
       "  config.solid_queue.connects_to = { database: { writing: :queue } }\n"
   end

data/lib/solid_queue/app_executor.rb

@@ -4,7 +4,7 @@ module SolidQueue
   module AppExecutor
     def wrap_in_app_executor(&block)
       if SolidQueue.app_executor
-        SolidQueue.app_executor.wrap(&block)
+        SolidQueue.app_executor.wrap(source: "application.solid_queue", &block)
       else
         yield
       end

data/lib/solid_queue/configuration.rb

@@ -2,6 +2,12 @@
 
 module SolidQueue
   class Configuration
+    include ActiveModel::Model
+
+    validate :ensure_configured_processes
+    validate :ensure_valid_recurring_tasks
+    validate :ensure_correctly_sized_thread_pool
+
     class Process < Struct.new(:kind, :attributes)
       def instantiate
         "SolidQueue::#{kind.to_s.titleize}".safe_constantize.new(**attributes)
@@ -36,14 +42,46 @@ module SolidQueue
       end
     end
 
-    def max_number_of_threads
-      # At most "threads" in each worker + 1 thread for the worker + 1 thread for the heartbeat task
-      workers_options.map { |options| options[:threads] }.max + 2
+    def error_messages
+      if configured_processes.none?
+        "No workers or processed configured. Exiting..."
+      else
+        error_messages = invalid_tasks.map do |task|
+            all_messages = task.errors.full_messages.map { |msg| "\t#{msg}" }.join("\n")
+            "#{task.key}:\n#{all_messages}"
+          end
+          .join("\n")
+
+        "Invalid processes configured:\n#{error_messages}"
+      end
     end
 
     private
       attr_reader :options
 
+      def ensure_configured_processes
+        unless configured_processes.any?
+          errors.add(:base, "No processes configured")
+        end
+      end
+
+      def ensure_valid_recurring_tasks
+        unless skip_recurring_tasks? || invalid_tasks.none?
+          error_messages = invalid_tasks.map do |task|
+            "- #{task.key}: #{task.errors.full_messages.join(", ")}"
+          end
+
+          errors.add(:base, "Invalid recurring tasks:\n#{error_messages.join("\n")}")
+        end
+      end
+
+      def ensure_correctly_sized_thread_pool
+        if (db_pool_size = SolidQueue::Record.connection_pool&.size) && db_pool_size < estimated_number_of_threads
+          errors.add(:base, "Solid Queue is configured to use #{estimated_number_of_threads} threads but the " +
+            "database connection pool is #{db_pool_size}. Increase it in `config/database.yml`")
+        end
+      end
+
       def default_options
         {
           config_file: Rails.root.join(ENV["SOLID_QUEUE_CONFIG"] || DEFAULT_CONFIG_FILE_PATH),
@@ -54,6 +92,10 @@ module SolidQueue
         }
       end
 
+      def invalid_tasks
+        recurring_tasks.select(&:invalid?)
+      end
+
       def only_work?
         options[:only_work]
       end
@@ -100,7 +142,7 @@ module SolidQueue
       def recurring_tasks
         @recurring_tasks ||= recurring_tasks_config.map do |id, options|
           RecurringTask.from_configuration(id, **options)
-        end.select(&:valid?)
+        end
       end
 
       def processes_config
@@ -147,5 +189,11 @@ module SolidQueue
           {}
         end
       end
+
+      def estimated_number_of_threads
+        # At most "threads" in each worker + 1 thread for the worker + 1 thread for the heartbeat task
+        thread_count = workers_options.map { |options| options.fetch(:threads, WORKER_DEFAULTS[:threads]) }.max
+        (thread_count || 1) + 2
+      end
   end
 end

data/lib/solid_queue/dispatcher.rb

@@ -24,7 +24,8 @@ module SolidQueue
     private
       def poll
         batch = dispatch_next_batch
-        batch.size
+
+        batch.size.zero? ? polling_interval : 0.seconds
       end
 
       def dispatch_next_batch

data/lib/solid_queue/log_subscriber.rb

@@ -145,6 +145,7 @@ class SolidQueue::LogSubscriber < ActiveSupport::LogSubscriber
   end
 
   def replace_fork(event)
+    supervisor_pid = event.payload[:supervisor_pid]
     status = event.payload[:status]
     attributes = event.payload.slice(:pid).merge \
       status: (status.exitstatus || "no exit status set"),
@@ -155,7 +156,7 @@ class SolidQueue::LogSubscriber < ActiveSupport::LogSubscriber
 
     if replaced_fork = event.payload[:fork]
       info formatted_event(event, action: "Replaced terminated #{replaced_fork.kind}", **attributes.merge(hostname: replaced_fork.hostname, name: replaced_fork.name))
-    else
+    elsif supervisor_pid != 1 # Running Docker, possibly having some processes that have been reparented
       warn formatted_event(event, action: "Tried to replace forked process but it had already died", **attributes)
     end
   end

data/lib/solid_queue/processes/interruptible.rb

@@ -7,31 +7,27 @@ module SolidQueue::Processes
     end
 
     private
-      SELF_PIPE_BLOCK_SIZE = 11
 
       def interrupt
-        self_pipe[:writer].write_nonblock(".")
-      rescue Errno::EAGAIN, Errno::EINTR
-        # Ignore writes that would block and retry
-        # if another signal arrived while writing
-        retry
+        queue << true
       end
 
+      # Sleeps for 'time'.  Can be interrupted asynchronously and return early via wake_up.
+      # @param time [Numeric] the time to sleep. 0 returns immediately.
+      # @return [true, nil]
+      # * returns `true` if an interrupt was requested via #wake_up between the
+      #   last call to `interruptible_sleep` and now, resulting in an early return.
+      # * returns `nil` if it slept the full `time` and was not interrupted.
       def interruptible_sleep(time)
-        if time > 0 && self_pipe[:reader].wait_readable(time)
-          loop { self_pipe[:reader].read_nonblock(SELF_PIPE_BLOCK_SIZE) }
-        end
-      rescue Errno::EAGAIN, Errno::EINTR
+        # Invoking this from the main thread may result in significant slowdown.
+        # Utilizing asynchronous execution (Futures) addresses this performance issue.
+        Concurrent::Promises.future(time) do |timeout|
+          queue.pop(timeout:).tap { queue.clear }
+        end.value
       end
 
-      # Self-pipe for signal-handling (http://cr.yp.to/docs/selfpipe.html)
-      def self_pipe
-        @self_pipe ||= create_self_pipe
-      end
-
-      def create_self_pipe
-        reader, writer = IO.pipe
-        { reader: reader, writer: writer }
+      def queue
+        @queue ||= Queue.new
       end
   end
 end

data/lib/solid_queue/processes/poller.rb

@@ -25,11 +25,11 @@ module SolidQueue::Processes
         loop do
           break if shutting_down?
 
-          wrap_in_app_executor do
-            unless poll > 0
-              interruptible_sleep(polling_interval)
-            end
+          delay = wrap_in_app_executor do
+            poll
           end
+
+          interruptible_sleep(delay)
         end
       ensure
         SolidQueue.instrument(:shutdown_process, process: self) do

data/lib/solid_queue/processes/runnable.rb

@@ -41,10 +41,6 @@ module SolidQueue::Processes
         end
       end
 
-      def run
-        raise NotImplementedError
-      end
-
       def shutting_down?
         stopped? || (running_as_fork? && supervisor_went_away?) || finished? || !registered?
       end

data/lib/solid_queue/scheduler/recurring_schedule.rb

@@ -41,6 +41,7 @@ module SolidQueue
 
     private
       def persist_tasks
+        SolidQueue::RecurringTask.static.where.not(key: task_keys).delete_all
         SolidQueue::RecurringTask.create_or_update_all configured_tasks
       end
 

data/lib/solid_queue/supervisor/pidfile.rb

@@ -29,7 +29,7 @@ module SolidQueue
         else
           FileUtils.mkdir_p File.dirname(path)
         end
-      rescue Errno::ESRCH => e
+      rescue Errno::ESRCH
         # Process is dead, ignore, just delete the file
         delete
       rescue Errno::EPERM

data/lib/solid_queue/supervisor.rb

@@ -10,10 +10,10 @@ module SolidQueue
         SolidQueue.supervisor = true
         configuration = Configuration.new(**options)
 
-        if configuration.configured_processes.any?
+        if configuration.valid?
           new(configuration).tap(&:start)
         else
-          abort "No workers or processed configured. Exiting..."
+          abort configuration.errors.full_messages.join("\n") + "\nExiting..."
         end
       end
     end

data/lib/solid_queue/version.rb

@@ -1,3 +1,3 @@
 module SolidQueue
-  VERSION = "1.0.0"
+  VERSION = "1.1.1"
 end

data/lib/solid_queue/worker.rb

@@ -7,6 +7,7 @@ module SolidQueue
     after_boot :run_start_hooks
     before_shutdown :run_stop_hooks
 
+
     attr_accessor :queues, :pool
 
     def initialize(**options)
@@ -29,7 +30,7 @@ module SolidQueue
             pool.post(execution)
           end
 
-          executions.size
+          pool.idle? ? polling_interval : 10.minutes
         end
       end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_queue
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Rosa Gutierrez
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-26 00:00:00.000000000 Z
+date: 2024-12-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -98,16 +98,16 @@ dependencies:
   name: debug
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.9'
 - !ruby/object:Gem::Dependency
   name: mocha
   requirement: !ruby/object:Gem::Requirement
@@ -192,6 +192,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Database-backed Active Job backend.
 email:
 - rosa@37signals.com
@@ -302,7 +330,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: Database-backed Active Job backend.