Showing
3 changed files
with
116 additions
and
0 deletions
| 1 | +package org.onlab.onos.store.service; | ||
| 2 | + | ||
| 3 | +/** | ||
| 4 | + * A lock is a tool for controlling access to a shared resource by multiple processes. | ||
| 5 | + * Commonly, a lock provides exclusive access to a resource such as a network device | ||
| 6 | + * or exclusive permission to a controller to perform a particular role such as serve | ||
| 7 | + * as the master controller for a device. | ||
| 8 | + * At any given time one and only process can acquire the lock. | ||
| 9 | + */ | ||
| 10 | +public interface Lock { | ||
| 11 | + | ||
| 12 | + /** | ||
| 13 | + * Acquires the lock. | ||
| 14 | + * If the lock is not available then the caller thread becomes | ||
| 15 | + * disabled for thread scheduling purposes and lies dormant until | ||
| 16 | + * the lock has been acquired. | ||
| 17 | + * <p> | ||
| 18 | + * Locks are reentrant. A thread invoking this method multiple times | ||
| 19 | + * without an intervening unlock or lease expiration must invoke unlock() | ||
| 20 | + * the same number of times before the lock is released (unless the lease expires). | ||
| 21 | + * When this method is invoked for a lock that is already acquired, | ||
| 22 | + * the lease time will be set to the maximum of the remaining lease time | ||
| 23 | + * from the previous invocation, or leaseDurationMillis. | ||
| 24 | + * @param leaseDurationMillis the number of milliseconds to hold the | ||
| 25 | + * lock after granting it, before automatically releasing it if it hasn't | ||
| 26 | + * already been released by invoking unlock(). Must be in the range | ||
| 27 | + * (0, MAX_LEASE_MILLIS] | ||
| 28 | + */ | ||
| 29 | + void lock(long leaseDurationMillis); | ||
| 30 | + | ||
| 31 | + /** | ||
| 32 | + * Acquires the lock only if it is free at the time of invocation. | ||
| 33 | + * @param leaseDurationMillis the number of milliseconds the must be | ||
| 34 | + * locked after it is granted, before automatically releasing it if it hasn't | ||
| 35 | + * already been released by an invocation of unlock(). Must be in the range | ||
| 36 | + * (0, MAX_LEASE_MILLIS] | ||
| 37 | + * @return true if the lock was acquired and false otherwise | ||
| 38 | + */ | ||
| 39 | + boolean tryLock(long leaseDurationMillis); | ||
| 40 | + | ||
| 41 | + /** | ||
| 42 | + * Acquires the lock if it is free within the given waiting | ||
| 43 | + * time and the current thread has not been interrupted. | ||
| 44 | + * @param waitTimeMillis the maximum time (in milliseconds) to wait for the lock | ||
| 45 | + * @param leaseDurationMillis the number of milliseconds to hold the | ||
| 46 | + * lock after granting it, before automatically releasing it if it hasn't | ||
| 47 | + * already been released by invoking unlock(Object). Must be in the range | ||
| 48 | + * (0, MAX_LEASE_MILLIS] | ||
| 49 | + * @return true if the lock was acquired and false if the waiting time | ||
| 50 | + * elapsed before the lock was acquired | ||
| 51 | + */ | ||
| 52 | + boolean tryLock(long waitTimeMillis, long leaseDurationMillis); | ||
| 53 | + | ||
| 54 | + /** | ||
| 55 | + * Returns true if this Lock instance currently holds the lock. | ||
| 56 | + * @return true if this instance is the owner of the lock. | ||
| 57 | + */ | ||
| 58 | + boolean isLocked(); | ||
| 59 | + | ||
| 60 | + /** | ||
| 61 | + * Releases the lock. | ||
| 62 | + */ | ||
| 63 | + void unlock(); | ||
| 64 | + | ||
| 65 | + /** | ||
| 66 | + * Extends the lease for this lock. | ||
| 67 | + * @param extensionDurationMillis is the amount of additional | ||
| 68 | + * time to add to the end of the current expiration time. For example, | ||
| 69 | + * if the lock is currently set to expire at time T, a successful call to | ||
| 70 | + * extendLease with an argument of 5000 will cause the lock to | ||
| 71 | + * now expire at 5 seconds past T. | ||
| 72 | + * @return true if the extension is successful, false otherwise. Note | ||
| 73 | + * that a failure to extend the lease does not result in unlocking. The lock | ||
| 74 | + * will be released either by an explicit call to unlock or when previously | ||
| 75 | + * acquired lease runs out. | ||
| 76 | + */ | ||
| 77 | + boolean extendLease(long extensionDurationMillis); | ||
| 78 | +} | ||
| ... | \ No newline at end of file | ... | \ No newline at end of file |
| 1 | +package org.onlab.onos.store.service; | ||
| 2 | + | ||
| 3 | +/** | ||
| 4 | + * Listener for lock events. | ||
| 5 | + */ | ||
| 6 | +public interface LockEventListener { | ||
| 7 | + | ||
| 8 | + /** | ||
| 9 | + * Notifies the listener of a lock's lease expiration event. | ||
| 10 | + * @param lock lock whose lease has expired. | ||
| 11 | + */ | ||
| 12 | + void leaseExpired(Lock lock); | ||
| 13 | +} |
| 1 | +package org.onlab.onos.store.service; | ||
| 2 | + | ||
| 3 | +public interface LockService { | ||
| 4 | + | ||
| 5 | + /** | ||
| 6 | + * Create a new lock instance. | ||
| 7 | + * A successful return from this method does not mean the resource guarded by the path is locked. | ||
| 8 | + * The caller is expect to call Lock.lock() to acquire the lock. | ||
| 9 | + * @param path unique lock name. | ||
| 10 | + * @return | ||
| 11 | + */ | ||
| 12 | + Lock create(String path); | ||
| 13 | + | ||
| 14 | + /** | ||
| 15 | + * Adds a listener to be notified of lock events. | ||
| 16 | + * @param listener listener to be added. | ||
| 17 | + */ | ||
| 18 | + void addListener(LockEventListener listener); | ||
| 19 | + | ||
| 20 | + /** | ||
| 21 | + * Removes a listener that was previously added. | ||
| 22 | + * @param listener listener to be removed. | ||
| 23 | + */ | ||
| 24 | + void removeListener(LockEventListener listener); | ||
| 25 | +} | ||
| ... | \ No newline at end of file | ... | \ No newline at end of file |
-
Please register or login to post a comment