io.atomix.coordination

Class DistributedLock

java.lang.Object

io.atomix.resource.AbstractResource

io.atomix.coordination.DistributedLock

All Implemented Interfaces:

Resource

public class DistributedLock
extends AbstractResource

Provides a mechanism for synchronizing access to cluster-wide shared resources.

The distributed lock resource provides a mechanism for nodes to synchronize access to cluster-wide shared resources. This interface is an asynchronous version of Java's Lock.

   
   atomix.create("lock", DistributedLock::new).thenAccept(lock -> {
     lock.lock().thenRun(() -> {
       ...
       lock.unlock();
     });
   });
   
 

Locks are implemented as a simple replicated queue that tracks which client currently holds a lock. When a lock is locked, if the lock is available then the requesting resource instance will immediately receive the lock, otherwise the lock request will be queued. When a lock is unlocked, the next lock requester will be granted the lock.

Distributed locks require no polling from the client. Locks are granted via session events published by the Atomix cluster to the lock instance. In the event that a lock's client becomes disconnected from the cluster, its session will expire after the configured cluster session timeout and the lock will be automatically released.

Author:

Jordan Halterman

Constructor Summary

Constructors

Constructor and Description
DistributedLock(RaftClient client)

Method Summary

Modifier and Type	Method and Description
CompletableFuture<Void>	lock() Acquires the lock.
CompletableFuture<Boolean>	tryLock() Attempts to acquire the lock if available.
CompletableFuture<Boolean>	tryLock(Duration timeout) Attempts to acquire the lock if available within the given timeout.
CompletableFuture<Void>	unlock() Releases the lock.
DistributedLock	with(Consistency consistency)

Methods inherited from class io.atomix.resource.AbstractResource

context, delete, equals, hashCode, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DistributedLock

public DistributedLock(RaftClient client)

Method Detail

with

public DistributedLock with(Consistency consistency)

Specified by:

with in interface Resource

Overrides:

with in class AbstractResource

lock

public CompletableFuture<Void> lock()

Acquires the lock.

When the lock is acquired, this lock instance will publish a lock request to the cluster and await an event granting the lock to this instance. The returned CompletableFuture will not be completed until the lock has been acquired.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.join() method to block the calling thread:

   
   lock.lock().join();
   
 

Alternatively, to execute the operation asynchronous and be notified once the lock is acquired in a different thread, use one of the many completable future callbacks:

   
   lock.lock().thenRun(() -> System.out.println("Lock acquired!"));
   
 

Returns:

A completable future to be completed once the lock has been acquired.

tryLock

public CompletableFuture<Boolean> tryLock()

Attempts to acquire the lock if available.

When the lock is acquired, this lock instance will publish an immediate lock request to the cluster. If the lock is available, the lock will be granted and the returned CompletableFuture will be completed successfully. If the lock is not immediately available, the CompletableFuture will be completed false.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() method to block the calling thread:

   
   if (lock.tryLock().get()) {
     System.out.println("Lock acquired!");
   } else {
     System.out.println("Lock failed!");
   }
   
 

Alternatively, to execute the operation asynchronous and be notified once the lock is acquired in a different thread, use one of the many completable future callbacks:

   
   lock.tryLock().thenAccept(locked -> {
     if (locked) {
       System.out.println("Lock acquired!");
     } else {
       System.out.println("Lock failed!");
     }
   });
   
 

Returns:

A completable future to be completed with a boolean indicating whether the lock was acquired.

tryLock

public CompletableFuture<Boolean> tryLock(Duration timeout)

Attempts to acquire the lock if available within the given timeout.

When the lock is acquired, this lock instance will publish an immediate lock request to the cluster. If the lock is available, the lock will be granted and the returned CompletableFuture will be completed successfully. If the lock is not immediately available, the lock request will be queued until the lock comes available. If the lock timeout expires, the lock request will be cancelled and the returned CompletableFuture will be completed false.

Timeouts and wall-clock time The provided timeout may not ultimately be representative of the actual timeout in the cluster. Because of clock skew and determinism requirements, the actual timeout may be arbitrarily greater, but not less, than the provided timeout. However, time will always progress monotonically. That is, time will never go in reverse. A timeout of 10 seconds will always be greater than a timeout of 9 seconds, but the times simply may not match actual wall-clock time.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.get() method to block the calling thread:

   
   if (lock.tryLock(Duration.ofSeconds(10)).get()) {
     System.out.println("Lock acquired!");
   } else {
     System.out.println("Lock failed!");
   }
   
 

Alternatively, to execute the operation asynchronous and be notified once the lock is acquired in a different thread, use one of the many completable future callbacks:

   
   lock.tryLock(Duration.ofSeconds(10)).thenAccept(locked -> {
     if (locked) {
       System.out.println("Lock acquired!");
     } else {
       System.out.println("Lock failed!");
     }
   });
   
 

Parameters:

timeout - The duration within which to acquire the lock.

Returns:

A completable future to be completed with a boolean indicating whether the lock was acquired.

unlock

public CompletableFuture<Void> unlock()

Releases the lock.

When the lock is released, the lock instance will publish an unlock request to the cluster. Once the lock has been released, if any other instances of this resource are waiting for a lock on this or another node, the lock will be acquired by the waiting instance before this unlock operation is completed. Once the lock has been released and granted to any waiters, the returned CompletableFuture will be completed.

This method returns a CompletableFuture which can be used to block until the operation completes or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.join() method to block the calling thread:

   
   lock.unlock().join();
   
 

Alternatively, to execute the operation asynchronous and be notified once the lock is acquired in a different thread, use one of the many completable future callbacks:

   
   lock.unlock().thenRun(() -> System.out.println("Lock released!"));
   
 

Returns:

A completable future to be completed once the lock has been released.