io.hekate.lock

Interface DistributedLock

All Superinterfaces:

Lock

public interface DistributedLock
extends Lock

Distributed lock.

Distributed lock provides support for controlling access to a shared resource or a critical section at the cluster-wide level. At any point in time only one thread on any cluster node can gain a lock with the same name. All other threads, either running on the same node or on remote nodes, will await for the lock to be released before getting a chance to obtain the lock.

Below is the example of how an instance of DistributedLock can be obtained from the LockService and used for locking operations:

// Get lock with name 'example.lock'.
DistributedLock lock = hekate.locks().region("region1").get("example.lock");

// Acquire the lock.
lock.lock();

try {
    // Do some work ...
    thereCanBeOnlyOne();
} finally {
    // Make sure that lock is always released after the work is done.
    lock.unlock();
}

For more details about distributed locks and their usage please see the documentation of LockService interface.

See Also:

LockService

Method Summary

Modifier and Type	Method and Description
int	holdCount() Returns the number of holds on this lock by the current thread.
boolean	isHeldByCurrentThread() Returns true if this lock is held by the current thread.
Future<?>	lockAsync(Executor executor, AsyncLockCallback callback) Performs asynchronous locking and notifies the specified callback upon the lock status changes.
String	name() Returns the name of this lock.
Condition	newCondition() Unsupported operation.
Optional<LockOwnerInfo>	owner() Returns an information about the node that is currently holding this lock.
String	regionName() Returns the name of the region this lock belongs to.
boolean	tryLock(long timeout, TimeUnit unit) Tries to acquire the lock with the given timeout.
void	unlock() Unlocks the lock.
void	unlockAsync() Schedules unlock operation for asynchronous processing but doesn't await for its completion.

Methods inherited from interface java.util.concurrent.locks.Lock

lock, lockInterruptibly, tryLock

Method Detail

name

String name()

Returns the name of this lock.

Returns:

Name of this lock.

See Also:

LockRegion.get(String)

regionName

String regionName()

Returns the name of the region this lock belongs to.

Returns:

Name of the lock region.

See Also:

LockService.region(String)

holdCount

int holdCount()

Returns the number of holds on this lock by the current thread.

Returns:

Number of holds on this lock by the current thread.

isHeldByCurrentThread

boolean isHeldByCurrentThread()

Returns true if this lock is held by the current thread.

Returns:

true if this lock is held by the current thread.

lockAsync

Future<?> lockAsync(Executor executor,
                    AsyncLockCallback callback)

Performs asynchronous locking and notifies the specified callback upon the lock status changes.

The specified Executor instance will be used to perform all notifications of the callback object. Thus it is highly recommended to use a single-threaded executor (f.e. Executors.newSingleThreadExecutor()) so that all the callback notifications would be performed on the same thread. Otherwise the callback notification order can be completely unpredictable.

For details about the callback notification order please see the documentation of AsyncLockCallback interface.

The Future object, that is returned by this method, can be used to wait for asynchronous lock acquisition (after the lock have been acquired but before the AsyncLockCallback.onLockAcquire(DistributedLock) method gets notified).

Parameters:

executor - Executor to perform asynchronous notifications of callback methods.

callback - Callback.

Returns:

Future object that can be used to await for the lock acquisition.

unlock

void unlock()

Unlocks the lock. If current thread is not the lock owner then IllegalMonitorStateException will be thrown.

Specified by:

unlock in interface Lock

unlockAsync

void unlockAsync()

Schedules unlock operation for asynchronous processing but doesn't await for its completion. If current thread is not the lock owner then IllegalMonitorStateException will be thrown.

tryLock

boolean tryLock(long timeout,
                TimeUnit unit)
         throws InterruptedException

Tries to acquire the lock with the given timeout.

Note: timeout doesn't consider communication overhead of locking. For example, if timeout is 100ms and it takes 50ms to communicate with the cluster members in order to try the lock then the total wait time before giving up will be 150ms.

Specified by:

tryLock in interface Lock

Parameters:

timeout - Maximum time to wait for the lock (doesn't include the communication overhead).

unit - Time unit of timeout.

Returns:

true if the lock was acquired and false if the waiting time elapsed before the lock was acquired.

Throws:

InterruptedException - Signals that current thread is interrupted while acquiring the lock.

owner

Optional<LockOwnerInfo> owner()
                       throws InterruptedException

Returns an information about the node that is currently holding this lock.

Note that this operation requires a network round trip to the lock manager node and there are no guarantees that lock owner will not change by the time when result is returned from this method.

Returns:

Lock owner.

Throws:

InterruptedException - Signal that current thread was interrupted while awaiting for lock owner information.

newCondition

Condition newCondition()

Unsupported operation.

Specified by:

newCondition in interface Lock

Returns:

Unsupported operation.