With Solid Queue, how does limits_concurrency on a job class work, and what do its key:, to:, duration: and on_conflict: options do?
answer
- a semaphore per key, at enqueue
- key: required, to: defaults to 1
- blocked until a job finishes
- duration is a failsafe, 3 minutes
- :block by default, or :discard
basics
~20 slimits_concurrency lets Solid Queue run at most to: jobs with the same computed key at once; extras are blocked until one finishes, or dropped with on_conflict: :discard. duration: (3 minutes by default) is a failsafe for semaphores nobody released.
solid answer
~50 s`limits_concurrency` is a Solid Queue extension to Active Job. When a job is enqueued, Solid Queue computes its **key**, from a symbol, string or proc over the arguments (an Active Record result becomes `group/Class/id`), and checks a **semaphore** for it. If fewer than `to:` (default 1) jobs hold it, the job becomes ready; otherwise it is **blocked**, or with `on_conflict: :discard` dropped. When a holder finishes, successfully or not, it signals the semaphore and unblocks the next job. `duration:` (default `SolidQueue.default_concurrency_control_period`, 3 minutes) is a **failsafe**: if a crashed holder never signals, blocked jobs become eligible after it, checked during the dispatcher's concurrency maintenance. `group:` (default the class name) lets several classes share limits. It limits overlap, not order, applies to delayed jobs when they fall due, defeats `perform_all_later`'s bulk insert and adds overhead, so throttle with a dedicated queue and few threads instead.
go deeper
Know that Solid Queue's limits_concurrency can keep two jobs for the same record from running at the same time.
Explain key, to, group and on_conflict, and how blocked jobs are released when a holder finishes.
Set duration above real run times, keep jobs idempotent despite the limit, and use queues and thread counts instead of semaphores for throttling.
Decide where mutual exclusion belongs: in the queue, in the database with locks, or in the domain model, and what each costs at scale.
## The problem it solves On a newsletter platform, building a digest for one newsletter reads its posts, renders a template and writes a digest record. Two builds for the same newsletter running at once would race and could send subscribers two digests. Builds for *different* newsletters should still run in parallel. **`limits_concurrency`**, which Solid Queue adds to every Active Job class, expresses exactly that: ```ruby class BuildDigestJob < ApplicationJob queue_as :digests limits_concurrency to: 1, key: ->(newsletter) { newsletter }, duration: 15.minutes def perform(newsletter) DigestBuilder.new(newsletter).build_and_store! end end ``` ## The options | Option | Default | Meaning | |---|---|---| | `key:` | required | symbol, string or proc over the job's arguments that groups jobs | | `to:` | `1` | how many jobs with that key may run at the same time | | `duration:` | `SolidQueue.default_concurrency_control_period` (3 minutes) | failsafe before a stuck semaphore is released | | `group:` | the job class name | lets several job classes share one limit | | `on_conflict:` | `:block` | `:block` waits; `:discard` drops the newcomer | When the proc returns an Active Record object, the key is built from the group, the class name and the id, for example `BuildDigestJob/Newsletter/42`. ## How it works: semaphores at enqueue time 1. When the job is enqueued, Solid Queue computes its concurrency key and looks at the **semaphore** row for it in `solid_queue_semaphores`. 2. If the semaphore still has room, the job claims a slot and becomes **ready**, so workers can pick it up. 3. Otherwise the job becomes a **blocked execution** with `:block`, or is not enqueued at all with `:discard`. 4. When a running job finishes, whether it succeeded or failed, it **signals** the semaphore and unblocks the next job with that key, moving it from blocked to ready. Unblocked jobs then wait for a worker like any other. 5. If a holder never signals, because its process was killed, the **`duration`** expires. The dispatcher's **concurrency maintenance**, every 600 seconds by default, then releases as many blocked jobs as the limit allows. So `duration` is not a job timeout. It is the window during which the limit is guaranteed. A job that legitimately runs longer than `duration` can end up overlapping with the next one, so set it well above the job's normal run time. ## Guarantees and their limits - **No ordering guarantee.** Only overlap is limited; blocked jobs are released by priority, and queue order is ignored when unblocking. - **Delayed jobs are checked when due.** A job enqueued with `set(wait:)` claims its semaphore when the dispatcher makes it ready, not when it was scheduled. - **Bulk enqueueing loses its benefit.** `perform_all_later` has to enqueue concurrency-limited jobs one by one. - **Retries queue up again.** A retried job goes back through the semaphore like a new one. - **`:discard` has a sharp edge.** If a holder dies without signalling, every conflicting job is discarded until `duration` passes. ## Diagnosing a stuck key When digests for one newsletter stop going out while others flow, the semaphore is the first suspect: 1. Look for rows in `solid_queue_blocked_executions` with that newsletter's concurrency key; they are the jobs waiting their turn. 2. Check `solid_queue_semaphores` for the key: its value and expiry show whether a holder still has it. 3. Find the holder in `solid_queue_claimed_executions`. A holder whose process is gone means the semaphore will only free up after `duration`, at the next concurrency maintenance run. 4. If that wait is too long, the real fix is a shorter `duration` that still exceeds the job's run time, not a manual delete of semaphore rows. ## When not to use it Concurrency controls add writes for every enqueue and completion: semaphore rows, blocked executions, promotions. Solid Queue's own documentation advises against them for plain **throttling**, such as "at most 20 calls a second to the email provider". For that, route the jobs to a dedicated queue and give it a small worker: ```yaml production: workers: - queues: email_provider threads: 2 - queues: [ digests, default ] threads: 5 ``` ## Adapter scope `limits_concurrency` is defined by the `solid_queue` gem. Another backend, such as Sidekiq, does not enforce it, so a job that relies on it is tied to Solid Queue.
- Why might two BuildDigestJob runs for the same newsletter still overlap with to: 1?If the first run takes longer than `duration:`, or its process was killed without signalling, the semaphore expires and dispatcher maintenance can release the next job. The limit is guaranteed only for `duration`, so set it well above the job's real run time and keep the job itself safe to run twice.
- When would you choose on_conflict: :discard?When a newer job adds nothing while one is pending or running, such as a recount or refresh of the same newsletter's subscriber stats triggered by many events. Discarding collapses the burst into one run. The cost: if a holder dies without signalling, conflicting jobs are dropped until `duration` elapses, so the work must be safe to miss for that window.
- duration: kills a job that runs longer than the limit
- limits_concurrency guarantees jobs with the same key run in enqueue order
- The default on_conflict behaviour discards the extra jobs
- A failed job keeps holding its semaphore until duration expires
- limits_concurrency works the same on every Active Job backend