| /* |
| * Copyright 2014 Open Networking Laboratory |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.onosproject.store.service; |
| |
| import java.util.concurrent.CompletableFuture; |
| |
| /** |
| * 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. |
| */ |
| public interface Lock { |
| |
| /** |
| * Returns the path this lock will be used to guard from concurrent access. |
| * @return path. |
| */ |
| String path(); |
| |
| /** |
| * 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. |
| * <p> |
| * 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. |
| * @param 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 |
| */ |
| void lock(int leaseDurationMillis) throws InterruptedException; |
| |
| /** |
| * Acquires the lock asynchronously. |
| * @param leaseDurationMillis leaseDurationMillis the number of milliseconds the lock |
| * will be reserved before it becomes available for others. |
| * @return Future that can be used for blocking until lock is acquired. |
| */ |
| CompletableFuture<Void> lockAsync(int leaseDurationMillis); |
| |
| /** |
| * Acquires the lock only if it is free at the time of invocation. |
| * @param 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] |
| * @return true if the lock was acquired and false otherwise |
| */ |
| boolean tryLock(int leaseDurationMillis); |
| |
| /** |
| * Acquires the lock if it is free within the given waiting |
| * time and the current thread has not been interrupted. |
| * @param waitTimeMillis the maximum time (in milliseconds) to wait for the lock |
| * @param 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] |
| * @return 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 |
| */ |
| boolean tryLock(int waitTimeMillis, int leaseDurationMillis) throws InterruptedException; |
| |
| /** |
| * Returns true if this Lock instance currently holds the lock. |
| * @return true if this instance is the owner of the lock. |
| */ |
| boolean isLocked(); |
| |
| /** |
| * 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 |
| * @return epoch |
| */ |
| long epoch(); |
| |
| /** |
| * Releases the lock. |
| */ |
| void unlock(); |
| |
| /** |
| * 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. |
| * @param leaseDurationMillis extension duration. |
| * @return true if successfully extended expiration, false if attempt to |
| * extend expiration fails or if the path is currently not locked by this instance. |
| */ |
| boolean extendExpiration(int leaseDurationMillis); |
| } |