Skip to content

Semaphores

Garvit Joshi edited this page Nov 14, 2026 · 3 revisions

@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.

The lease is always fixed

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.

Semaphore keys stay in Redis

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.

Your code owns the permit count

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.

Permit leases follow your servers' clocks

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.

Related limitations

Clone this wiki locally