Class LoomLinearizableLock

java.lang.Object
com.loomcache.client.LoomLinearizableLock
public final class LoomLinearizableLock extends Object
Client-side distributed linearizable lock proxy.

A linearizable lock provides mutual exclusion across the cluster with support for fencing tokens. Fence tokens prevent split-brain anomalies in distributed systems by invalidating old lock-holders' operations. When a lock is released, a new fence token is issued on re-acquisition, invalidating any operations performed under the old fence token.

Fencing Token Semantics

A fencing token is a monotonically increasing integer assigned when a lock is acquired. All requests to protected resources must include the current fence token; the resource server rejects requests with outdated tokens. This prevents the "stale writes" problem where a process holding an old lock token (due to network delay) corrupts data.

Lock Ownership

Lock ownership is validated via requester ID. A lock can only be released by the process that acquired it (identified by requester ID).

Thread Safety

This class is thread-safe. Multiple threads may attempt to acquire the same lock. However, only one thread holds the lock at a time.

Usage Example

LoomConsistencySubsystem cp = client.consistencySubsystem();
LoomLinearizableLock lock = cp.getLock("resource-1");

// Try to acquire with timeout
long fence = lock.tryLock(Duration.ofSeconds(5));
if (fence > 0) {
    try {
        // Critical section — include fence token in requests
        protectedResource.update("data", fence);
    } finally {
        lock.unlock();
    }
}
Since:
1.4
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    getFence()
    Deprecated, for removal: This API element is subject to removal in a future version.
    This method acquires the lock.
    long
    lock()
    Acquires the lock, blocking until successful.
    long
    lockAndGetFence()
    Acquires the lock and returns the fence token.
    long
    tryLock(Duration timeout)
    Attempts to acquire the lock with a timeout.
    void
    unlock()
    Releases the lock held by the current requester.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • lock

      public long lock()
      Acquires the lock, blocking until successful.

      Returns a fence token that must be included in all requests made within the critical section to prevent stale writes in case of lock holder change.

      Returns:
      the fence token for this lock acquisition
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • tryLock

      public long tryLock(Duration timeout)
      Attempts to acquire the lock with a timeout.

      Returns a fence token if successful, or -1 if the lock was not acquired within the timeout period.

      Parameters:
      timeout - the maximum time to wait for the lock
      Returns:
      the fence token if acquired; -1 if timed out
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • unlock

      public void unlock()
      Releases the lock held by the current requester.

      Only the process that acquired the lock (identified by requester ID) can release it. After releasing, the lock becomes available for other requesters.

      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • lockAndGetFence

      public long lockAndGetFence()
      Acquires the lock and returns the fence token.

      WARNING: This method acquires the lock as a side effect. There is no read-only fence query in the current protocol. The caller holds the lock after this call and must release it via unlock().

      Returns:
      the fence token from the acquisition
      Throws:
      LoomException - if the operation fails or the cluster is unavailable

    • getFence

      @Deprecated(since="1.4", forRemoval=true) public long getFence()
      Deprecated, for removal: This API element is subject to removal in a future version.
      This method acquires the lock. Use lockAndGetFence() to make the lock-acquisition side effect explicit.
      Acquires the lock and returns the fence token.
      Returns:
      the fence token from the acquisition
      Throws:
      LoomException - if the operation fails or the cluster is unavailable