Design and Implementation of ylock: A Distributed ReentrantReadWriteLock Framework

1 Lock in Distributed Environment

Locks are the most common synchronization mechanism, but standard language locks like Java's ReentrantReadWriteLock or Go's RWMutex only work within a single process. In distributed systems, processes need coordination, which requires distributed locks that must balance exclusiveness, liveness, reentrancy, and fairness.

2 Available Distributed Locks

2.1 Dedicated Lock Service

Services such as Google Chubby run consensus algorithms (Paxos, Raft) to manage locks centrally, offering high configurability but high deployment cost and lower performance.

2.2 Lock Service on Common Middleware

Using middleware like Redis, Zookeeper, or etcd to implement locks is common; libraries such as Apache Curator provide ready‑made reentrant read‑write locks.

2.3 Self as Lock Service

Running consensus protocols (Paxos, Raft) directly among the lock participants avoids external services but requires multiple instances from the start and is rarely used in practice.

3 What We Need

For most business scenarios we need a lock that offers liveness, efficiency, and reasonable exclusiveness, with optional features like reentrancy, fairness, and shared/exclusive modes. Existing internal Redis‑based lock libraries lack these capabilities.

4 ylock: What & Why & How

ylock is a distributed lock framework providing a unified Lock and Locks API, supporting both Redis and Zookeeper engines, offering reentrancy, fairness, and monitoring out of the box.

Each lock is identified by a group (business prefix) and a name (specific resource).

public interface Lock {
  void lock();
  boolean lock(long time, TimeUnit unit);
  void unlock();
  void rlock();
  boolean rlock(long time, TimeUnit unit);
  void runlock();
  String name();
  String group();
}

public interface Locks {
  void lock(String name);
  boolean lock(String name, long time, TimeUnit unit);
  void unlock(String name);
  void rlock(String name);
  boolean rlock(String name, long time, TimeUnit unit);
  void runlock(String name);
  String group();
}

ylock provides two engine implementations:

RedisEngine : higher throughput, uses Lua scripts for atomic operations, maintains a waiting queue, exclusive owner, shared owners, and pending readers.

ZookeeperEngine : stronger exclusiveness, leverages Apache Curator's shared reentrant read‑write lock.

4.2.1 RedisLockEngine

Implements a ReentrantReadWriteLock‑like structure in Redis using keys such as waiter_queue , exclusive_owner , shared_owners , and pending_readers . Notification is handled via configurable polling (constant or exponential) to avoid the herd effect of pub‑sub.

4.2.2 ZookeeperLockEngine

Uses Curator's recipes to provide a robust reentrant read‑write lock, with additional in‑memory LockKeeper to track reentrancy counts.

4.3 Metrics

ylock emits Event and Span metrics for lock acquisition, release, and holding time. Metrics are grouped by group and can be exported to InfluxDB and visualized in Grafana.

4.4 Built‑in Spring Support

Provides a Spring Boot starter that auto‑configures the appropriate engine, supports annotation‑based injection ( @YLock , @YLocks ), and automatically registers metrics when an InfluxDB bean is present.

5 Conclusion

ylock delivers a practical distributed lock solution with reentrant read‑write semantics, balancing liveness and exclusiveness, and includes built‑in monitoring, making it suitable for everyday business scenarios where strict correctness can be relaxed in favor of efficiency.