Implementation and Pitfalls of Distributed Locks with Redis and Redisson Watchdog

In micro‑service scenarios, distributed locks are introduced to prevent concurrent processes and threads from accessing shared resources such as payment or order creation, ensuring business safety.

Requirements for a Redis‑based distributed lock

Mutual exclusion : Ensure that multiple processes/threads access the shared resource serially.

Lock expiration : Set a timeout to avoid lock hanging when a service crashes.

Automatic renewal : Prevent business timeout by automatically extending the lock before it expires.

Atomicity of multiple commands : Use Lua scripts to achieve atomic lock, unlock, and renewal operations.

Re‑entrancy : Use thread‑ID (UUID) to allow the same thread to reacquire the lock.

Prevent accidental deletion : Generate a globally unique ID before acquiring the lock and verify it before releasing.

Lock waiting notification : Use a publish/subscribe mechanism to notify waiting threads.

Redisson Watchdog Implementation

Using org.redisson.RedissonLock#tryLock() and org.redisson.RedissonLock#unlock as examples, the article shows the internal flow diagrams (images omitted for brevity). When the lock timeout is set to -1 and the lock is acquired successfully, Redisson starts a watchdog task that periodically renews the lock.

Each renewal first checks whether the lock has already been released; if renewal succeeds, the watchdog reschedules itself to continue renewing.

Lua‑based atomic lock operations

The lock acquisition and re‑entrance are performed via a Lua script; the script returns nil (Java null) on success, or the remaining TTL if the lock cannot be obtained.

RedisStrictCommand<Boolean> EVAL_NULL_BOOLEAN = new RedisStrictCommand<Boolean>("EVAL", new BooleanNullReplayConvertor());

If the script returns null, the lock is considered acquired and the renewal process starts; otherwise, false indicates failure.

Unlock operation analysis

The unlock flow also uses a Lua script to guarantee atomic release, preventing other clients from mistakenly deleting a lock they do not own.

Single‑instance lock vs. cluster lock

The presented lock implementation works only with a single Redis instance and does not support Redis Cluster. In a failover scenario (e.g., Sentinel), asynchronous replication may cause data loss if the master crashes before the slave finishes syncing.

Redis’s author provides the Redlock algorithm for cluster‑wide locks, but it has its own trade‑offs.

Redisson Watchdog Pitfalls and Recommendations

Do not pass a custom lock timeout; otherwise the watchdog will not renew.

Lock acquisition and release must occur in the same thread to preserve re‑entrancy logic.

Single‑instance failures and master‑slave switchovers can lead to lock loss.

To mitigate these issues:

Use Redlock for cluster environments, acknowledging its limitations.

Allocate dedicated Redis instances for locking, isolate them from other workloads, monitor health, and respond to alerts promptly.

Implement idempotent business logic as a safety net.

Conclusion

The article summarizes the key points of implementing a reliable distributed lock with Redis and Redisson, highlights common mistakes, and offers practical advice for production‑grade usage.

Redis learning resources: redis (password: 1988).