Handler Selection Strategies

Choose a starting slot when acquiring a handler process

Handler Selection Strategies

Set handler_selection per handler in handlers.toml. A worker scans from the chosen starting slot and takes an available process. If all slots are acquired, it waits for a release while its task claim is renewed.

Strategy	Starting slot
round-robin (default)	Next slot in a rotating sequence
first-available	Slot 0
random	A randomly chosen slot

[handlers.transform]
image = "transform:latest"
instances = 4
handler_selection = "round-robin"

[handlers.cached]
image = "cached-handler:latest"
instances = 2
handler_selection = "first-available"

The choice changes acquisition order; it does not increase pool capacity, preempt running tasks, or prove that one strategy is universally faster. Measure cache behavior, execution times, and contention with your handlers.

instances must be positive. Match pool size to the handler’s CPU, memory, and external-service limits. A worker count higher than useful handler concurrency can increase waiting without improving throughput. Startup launches persistent handler processes without a readiness handshake; submit a smoke task to verify initialization.

See handler configuration for timeout, memory, environment settings, and task selection for queue order.