Lock TTL & Timeouts
Relevant source files
The following files were used as context for generating this wiki page:
Lock TTL (Time-To-Live) and Timeouts are critical configuration parameters in sidekiq-unique-jobs that govern the lifecycle and acquisition behavior of unique locks in Redis. TTL ensures that locks eventually expire to prevent permanent deadlocks, while Timeouts define how long a process should wait to acquire a lock before failing or triggering a conflict strategy.
Sources: README.md:104-106, CLAUDE.md:144-147
Lock TTL (Time-To-Live)
The lock_ttl parameter defines the expiration time for a lock in Redis. It is measured in seconds and starts from the moment the lock is created, rather than when the job finishes executing. If no lock_ttl is provided, the system defaults to the global configuration or nil (no expiration), though specific lock types like :until_expired rely heavily on this value for their core functionality.
Sources: README.md:104, CLAUDE.md:144-147, spec/sidekiq_unique_jobs/lock_ttl_spec.rb:46-56
Calculation Logic
The SidekiqUniqueJobs::LockTTL class is responsible for calculating the final TTL value based on job options. It supports multiple types of input for the lock_ttl option:
- Numeric/String: Direct integer or float values.
- Proc: Dynamic calculation at runtime.
- Symbol: Calls a class method on the worker.
- Duration-like objects: Objects responding to
#to_i.
Sources: spec/sidekiq_unique_jobs/lock_ttl_spec.rb:68-112
The following diagram illustrates how the TTL is determined from various configuration sources:
TTL for Scheduled Jobs
For scheduled jobs, the system calculates the "time until scheduled" to ensure the lock persists until the job is intended to run. This is calculated by subtracting the current UTC time from the job's at timestamp.
Sources: spec/sidekiq_unique_jobs/lock_ttl_spec.rb:30-44
Lock Timeout
The lock_timeout defines how long the Locksmith should wait when attempting to acquire a lock that is currently held by another job.
Timeout Behaviors
- Zero (0): The default behavior. The system does not wait; it immediately fails to acquire the lock if a duplicate exists, triggering the conflict strategy.
- Positive Integer: The system will block and wait for the specified number of seconds for the lock to become available.
- Nil: In certain configurations, this may imply waiting indefinitely or using a default.
Sources: spec/sidekiq_unique_jobs/lock_config_spec.rb:71-105, spec/sidekiq_unique_jobs/locksmith_spec.rb:107-133
Configuration Reference
The following table summarizes the configuration options available for controlling TTL and Timeouts:
| Option | Type | Default | Description |
|---|---|---|---|
lock_ttl | Integer/Proc | nil | Expiration time for the lock in Redis (seconds). |
lock_timeout | Integer | 0 | Seconds to wait for lock acquisition. |
reaper_interval | Integer | 600 | Frequency (seconds) for cleaning up orphaned locks. |
Sources: README.md:104-113, spec/sidekiq_unique_jobs/lock_config_spec.rb:25-30
Lock Configuration Handling
The SidekiqUniqueJobs::LockConfig class normalizes these values from worker options, ensuring strings are converted to integers and handling fallbacks to global configuration.
Sources: spec/sidekiq_unique_jobs/lock_config_spec.rb:50-80
# Example worker configuration
sidekiq_options lock: :until_executed,
lock_ttl: 3600, # Expires after 1 hour
lock_timeout: 10 # Wait 10s for acquisition
Sources: README.md:135-137
Summary
Lock TTL and Timeouts provide the necessary constraints to ensure the sidekiq-unique-jobs system remains performant and resilient. While lock_ttl protects Redis memory and handles stale locks, lock_timeout controls the concurrency flow and determines how the system reacts to immediate duplicates. These settings can be applied globally via SidekiqUniqueJobs.configure or overridden on a per-worker basis using sidekiq_options.
Sources: README.md:102-115, CLAUDE.md:144-147