org.onosproject.store.service

Interface Lock

public interface Lock

A lock is a tool for controlling access to a shared resource by multiple processes. Commonly, a lock provides exclusive access to a resource such as a network device or exclusive permission to a controller to perform a particular role such as serve as the master controller for a device. At any given time one and only process can acquire the lock.

Method Summary

Modifier and Type	Method and Description
long	epoch() Returns the epoch for this lock.
boolean	extendExpiration(int leaseDurationMillis) Extends the expiration time for a lock that is currently owned by a specified duration.
boolean	isLocked() Returns true if this Lock instance currently holds the lock.
void	lock(int leaseDurationMillis) Acquires the lock.
CompletableFuture<Void>	lockAsync(int leaseDurationMillis) Acquires the lock asynchronously.
String	path() Returns the path this lock will be used to guard from concurrent access.
boolean	tryLock(int leaseDurationMillis) Acquires the lock only if it is free at the time of invocation.
boolean	tryLock(int waitTimeMillis, int leaseDurationMillis) Acquires the lock if it is free within the given waiting time and the current thread has not been interrupted.
void	unlock() Releases the lock.

Method Detail

path

String path()

Returns the path this lock will be used to guard from concurrent access.

Returns:

path.

lock

void lock(int leaseDurationMillis)
   throws InterruptedException

Acquires the lock. If the lock is not available then the caller thread becomes disabled for thread scheduling purposes and lies dormant until the lock has been acquired.

Locks are reentrant. A thread invoking this method multiple times without an intervening unlock or lease expiration must invoke unlock() the same number of times before the lock is released (unless the lease expires). When this method is invoked for a lock that is already acquired, the lease time will be set to the maximum of the remaining lease time from the previous invocation, or leaseDurationMillis.

Parameters:

leaseDurationMillis - the number of milliseconds to hold the lock after granting it, before automatically releasing it if it hasn't already been released by invoking unlock(). Must be in the range (0, LockManager.MAX_LEASE_MILLIS]

Throws:

InterruptedException - if the thread is interrupted while waiting

lockAsync

CompletableFuture<Void> lockAsync(int leaseDurationMillis)

Acquires the lock asynchronously.

Parameters:

leaseDurationMillis - leaseDurationMillis the number of milliseconds the lock will be reserved before it becomes available for others.

Returns:

Future that can be used for blocking until lock is acquired.

tryLock

boolean tryLock(int leaseDurationMillis)

Acquires the lock only if it is free at the time of invocation.

Parameters:

leaseDurationMillis - the number of milliseconds the must be locked after it is granted, before automatically releasing it if it hasn't already been released by an invocation of unlock(). Must be in the range (0, LockManager.MAX_LEASE_MILLIS]

Returns:

true if the lock was acquired and false otherwise

tryLock

boolean tryLock(int waitTimeMillis,
                int leaseDurationMillis)
         throws InterruptedException

Acquires the lock if it is free within the given waiting time and the current thread has not been interrupted.

Parameters:

waitTimeMillis - the maximum time (in milliseconds) to wait for the lock

leaseDurationMillis - the number of milliseconds to hold the lock after granting it, before automatically releasing it if it hasn't already been released by invoking unlock(Object). Must be in the range (0, LockManager.MAX_LEASE_MILLIS]

Returns:

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

Throws:

InterruptedException - if the thread is interrupted while waiting

isLocked

boolean isLocked()

Returns true if this Lock instance currently holds the lock.

Returns:

true if this instance is the owner of the lock.

epoch

long epoch()

Returns the epoch for this lock. If this lock is currently locked i.e. isLocked() returns true, epoch signifies the logical time when the lock was acquired. The concept of epoch lets one come up with a global ordering for all lock acquisition events

Returns:

epoch

unlock

void unlock()

Releases the lock.

extendExpiration

boolean extendExpiration(int leaseDurationMillis)

Extends the expiration time for a lock that is currently owned by a specified duration. The new expiration time is computed by adding the specified duration to the current time. If this point in time is earlier than the existing expiration time then this method has no effect.

Parameters:

leaseDurationMillis - extension duration.

Returns:

true if successfully extended expiration, false if attempt to extend expiration fails or if the path is currently not locked by this instance.