A claim statement takes one task row by default. When almost every claim finds a row, the claim loop sets the throughput of a worker. A batch claim lets one statement take up to 2, 4 or 8 rows. It is off by default.
Turn it on
use autumn_harvest::builder::WorkerConfig;
let config = WorkerConfig::default().with_claim_batch_max(8);
assert_eq!(config.claim_batch_max.map(std::num::NonZeroU8::get), Some(8));
with_claim_batch_max(n)sets the fieldclaim_batch_max, anOption<NonZeroU8>.0and1setNone, one row per claim.- A batch holds 2, 4 or 8 rows. A value above 8 claims at most 8 rows.
- The knob belongs to each worker. Workers with and without it can share a shard, and no migration is needed.
GET /admin/configreports the value asclaim_batch_max.WorkerRuntimeConfighas the same field. A struct literal ofWorkerConfigorWorkerRuntimeConfigneedsclaim_batch_max: None.
Batch size
Each claim loop takes its share of the free permits of each kind that it
may claim. The share is the free permits over max_concurrent_claims,
rounded up. The batch is the smallest share over those kinds, capped at
claim_batch_max. It then rounds down to 2, 4 or 8. A share under 2 sends
the single claim.
For example, a worker with 8 free workflow permits, 16 free activity permits and two claim loops gets a share of 4 rows. A loop with one free permit of one kind claims one row, however many permits of the other kind are free.
The loop holds one permit per row across the claim. So a slot tuner shrink cannot take the permit of a claimed row. The loop gives back the permits of the rows that it did not get.
Forms that keep one row per claim
Only the default claim has a batch form. A worker claims one row per statement when any of these applies:
- queue weights (
with_queue_weights); - fairness keys (
with_fairness_keys). Seefairness-keys.md; - priority ageing (
with_priority_aging_secsabove zero). Seeclaim-order.md; - an adaptive limit on any activity type (
with_adaptive_limit); - a cost hold (
with_cost_hold). Seecost-deferral.md; - a dispatch channel, such as Redis dispatch.
In owner mode, an owned workflow claim takes one row. When the owner decider runs on a shard, the poll beside it claims activities only, and those can batch.
How it works
queue::claim_task_batch_with_slots sends the batch claim. Its text
derives from the window form of the default claim. Three parts change:
seek_candidatelocks up to 2, 4 or 8 rows withFOR UPDATE SKIP LOCKED.candidatekeeps those rows in claim order. It stops before the first row after row 1 that carries a concurrency key or a rate-limit key. That is the key cut.run_expired_nowlists the rows whose run passed its deadline. The claim takes only the other rows.
The key cut. The cap re-check of the claim reads the statement snapshot. Two rows of one concurrency key would both pass it. One rate-limit bucket row also takes one debit, however many claims join it. So only the first kept row of a batch may carry a key. A key or a bucket meets at most one row of a batch. The cut keeps the longest such prefix.
An expired run stops only its own row. The claim reads the clock again
after it takes the rate-limit bucket lock. A run can pass its deadline while
the claim waits on that lock. That row then stays PENDING. It spends no
token and takes no concurrency-key lock. The claim still takes the other
rows of the batch. The materialized CTE claim_live holds the live rows,
so the claim never tests the key lock of a row that it then drops.
Each claimed row passes the post-claim rechecks of a single claim. The rechecks of all rows share one pipeline. A row that they give back is hinted after the commit. When the batch finds no row and sets the fallback flag, the full statement runs and takes one row at most.
A batch claim takes one claim slot per statement, as a single claim does. A claim that gets no slot sends no statement.
formal/verus/src/claim_batch.rs proves the batch size bounds and the key
cut. See testing/formal-methods.md. The
tests a_run_that_expires_during_the_claim_stops_only_its_own_row and
an_expired_row_takes_no_key_lock_and_its_peers_still_claim in
claim_batch_db_tests.rs check the expired-row rule.
Choose a value
On the throughput cell of the bench, 8 raised the median from 100.0 to
118.7 workflows/s over six alternating pairs. Every pair was faster. Claim
statements fell 37%, and their execution time fell 29%. One statement for
eight rows costs about 1.19 times one statement for one row. See
performance-claim-batch.md.
Use the batch when most claims find a row and the claim loop is the limit. It gains little when the queue is often empty, or when a worker has few free permits per loop.
Known limits:
- Rows of equal claim key rank by id inside a batch. A single claim takes any of them.
seek_candidatelocks rows that the cut then drops. A peer claim skips such a row for one statement.- The batch does not split by kind.
See also
claim-slots.md: a fleet-wide cap on the claims that run at once on one shard.docs/architecture.md: the claim loops of a worker.