Package 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 Detail

      • 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.

      • 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.