@ThreadSafe public class KeyWatchTracker extends Object implements Closeable
To limit memory consumption, instances are configured with a maximum maximum number of key watches supported, as well as a maximum lifetime for each key watch. When these limits are exceeded, one or more key watches is evicted and a corresponding spurious notification occurs.
Instances can optionally be configured to only weakly reference the returned ListenableFuture
's.
This prevents memory leaks if the user of this class is sloppy and fails to cancel()
them when no longer needed; however, it can also lead to missed notifications if the user of this class relies
on the listener registration functionality provided in the
ListenableFuture
interface, because with a listener registration, there is no longer any need
to directly reference the ListenableFuture
, and so it may be reclaimed before firing. Therefore,
by default strong references are used.
In any case, ListenableFuture
notifications are performed on a separate dedicated notification
thread to avoid re-entrancy issues.
For space efficiency, this class does not track the original values associated with a key. Therefore, spurious notifications can also occur if a value is changed, and then changed back to its original value.
Instances are thread safe.
KVTransaction.watchKey(byte[])
Modifier and Type | Field and Description |
---|---|
static long |
DEFAULT_CAPACITY
Default capacity (10000L).
|
static long |
DEFAULT_MAXIMUM_LIFETIME
Default maximum lifetime in seconds (2592000L).
|
static boolean |
DEFAULT_WEAK_REFERENCE
Default for the weak reference option (false).
|
Constructor and Description |
---|
KeyWatchTracker()
Default constructor.
|
KeyWatchTracker(long capacity,
long maxLifetime,
boolean weakReferences)
Constructor.
|
Modifier and Type | Method and Description |
---|---|
void |
absorb(KeyWatchTracker that)
Absorb all of the watches from the given instance into this one.
|
void |
close()
Close this instance.
|
void |
failAll(Exception e)
Discard all outstanding key watches and fail them with the given exception.
|
int |
getNumKeysWatched()
Count the number of keys being watched.
|
ListenableFuture<Void> |
register(byte[] key)
Register a new watch.
|
boolean |
trigger(byte[] key)
Trigger all watches associated with the given key.
|
boolean |
trigger(Iterable<byte[]> keys)
Trigger all watches associated with the given keys.
|
boolean |
trigger(KeyRange range)
Trigger all watches associated with keys in the given range.
|
boolean |
trigger(Mutations mutations)
Trigger all watches associated with the given mutations.
|
boolean |
triggerAll()
Trigger all watches.
|
public static final long DEFAULT_CAPACITY
public static final long DEFAULT_MAXIMUM_LIFETIME
public static final boolean DEFAULT_WEAK_REFERENCE
public KeyWatchTracker()
public KeyWatchTracker(long capacity, long maxLifetime, boolean weakReferences)
capacity
- maximum number of key watches allowedmaxLifetime
- maximum lifetime for a key watch in secondsweakReferences
- true to only weakly reference registered ListenableFuture
sIllegalArgumentException
- if capacity
or maxLifetime
is zero or negativepublic ListenableFuture<Void> register(byte[] key)
If the returned Future
is cancel()
'ed,
the watch is automatically unregistered.
key
- the key to watchListenableFuture
that returns key
when the value associated with key
is modifiedIllegalArgumentException
- if key
is nullpublic int getNumKeysWatched()
Note that the same key can be watched more than once, so this only counts keys being watched, not total watches.
public boolean trigger(byte[] key)
key
- the key that has been modifiedIllegalArgumentException
- if key
is nullpublic boolean trigger(Iterable<byte[]> keys)
keys
- keys that have been modifiedIllegalArgumentException
- if keys
is nullpublic boolean trigger(KeyRange range)
range
- range of keys that have been modifiedIllegalArgumentException
- if range
is nullpublic boolean trigger(Mutations mutations)
mutations
- mutationsIllegalArgumentException
- if mutations
is nullpublic boolean triggerAll()
public void failAll(Exception e)
e
- failing exceptionIllegalArgumentException
- if e
is nullpublic void absorb(KeyWatchTracker that)
that
- the instance to absorb into this onepublic void close()
All outstanding key watches will be canceled as if by failAll()
.
close
in interface Closeable
close
in interface AutoCloseable
Copyright © 2022. All rights reserved.