Madan Jampani

Added LockService interface.

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