Repository navigation
Semaphores
@DistributedSemaphore limits how many calls of a Spring bean method run at once per key, across
all instances of the application. Each call holds one permit while it runs, and permits sets how
many there are. A permit's lease is how long it can be held before it expires on its own.
@DistributedSemaphore(
key = "reports",
permits = "${reports.max-concurrent:5}",
waitTime = "2s",
leaseTime = "10m")
public Report build(String id) { ... }| Attribute | Default | Meaning |
|---|---|---|
key |
required | key template; see Key templates |
permits |
required | the number of permits, as a string so a ${...} placeholder works; must resolve to an integer greater than zero |
waitTime |
"" |
how long to wait for a permit; blank or zero means try once and give up |
leaseTime |
"" |
the lease of a permit; blank means locksmith.semaphore.lease-time (5 minutes by default) |
onFailure |
THROW |
THROW, SKIP or HANDLER; see Failure handling
|
handler |
not set | the SemaphoreFailureHandler bean type, required with HANDLER only |
The semaphore lives at the Redis key locksmith:semaphore:<key>. Each call holds one permit, and
so does a nested call with the same key on the same thread: unlike locks, semaphores are not
reentrant. With permits = 1, a method that holds the permit and calls another annotated method
on the same key never gets a second permit: the nested call waits out its waitTime and fails.
Redisson permits have no renewal. A permit expires leaseTime after it was acquired, even if the
method is still running; set it longer than the slowest call. When a method outruns it, the release
logs one WARN (Permit [...] was reported as not held at release ...) and the result is returned
as usual. leaseTime, when set, must be at least one millisecond.
A semaphore's Redis key stays after its last permit is released (about 80 bytes), and each instance keeps one small entry per key in memory. Build semaphore keys from a fixed set of names, not from unbounded values such as order ids; to handle one order at a time, use a lock, whose key is deleted when it is released.
Redis stores the count, and the annotation (or the permits(int) call) states it. The first acquire
of a key in a JVM, and the first acquire with a different count, writes the count to Redis:
- a semaphore that does not exist yet is created with that count;
- a semaphore that has another count is changed to it, and Locksmith logs an INFO line:
Semaphore [locksmith:semaphore:reports] permits changed from 5 to 8. Callers that make their first acquire of the key at the same moment can each log it.
The last writer wins. Each JVM writes its count once per key, and again only when its own count changes.
Two annotations with the same key text and different counts fail the startup with a
LocksmithConfigurationException that names both methods and both counts; only the key text is
compared, so keys built from arguments that resolve to the same value are not checked. Give each
count its own key, or read it from one property.
When the count in Redis can be wrong or missing
The programmatic API is not checked either: two counts for one key from one instance overwrite each other at every switch, with one INFO line each time, and two such acquires at the same moment can leave Redis with the other count until that instance acquires with the other count again, or an instance restarts.
During a rolling deploy that changes the count, an old instance that acquires the key for the first time after a new one did puts the old count back, and it stays there until an instance writes again, for example a new instance after its start.
If Redis loses the semaphore key, for example after a restart without persistence, the next acquire
that finds no free permit re-creates it with its count and logs one INFO line:
Semaphore [locksmith:semaphore:reports] had no permits in Redis; count set to 5 again. Until
then, acquires that wait see no free permit: the first one waits out its whole waitTime before it
re-creates the key, and the others with it, unless an acquire without waitTime comes first, which
re-creates the key at once and lets them in.
Redisson times a permit's lease with the clock of the application server, not with Redis, so keep the servers' clocks in sync: a server whose clock is off can end other servers' permits early, by up to the difference. Lock leases use Redis's own expiry and are not affected.