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