public final class WeakValueCache<K,T> extends Object implements ICachePolicy<K,T>
A memory sensitive cache using weak references for its values and object ids for its keys and backed by the CRUD operations of the persistence layer, which is assumed to implement a hard reference LRU or similar cache policy.
Performance can be dramatically effect by the selection of the size of the LRU cache and by the choice of soft vs. weak references. The interaction of these parameters and the choice of the load factor for the weak value and LRU caches is non-trivial. Good performance is observed for default settings, but you can see 2-4x or better improvements through a tuned cache. You need a performance benchmark in order to tune your cache. The best performance benchmark is a solid and representative sample of real operations performed by your application, e.g., loading data, navigating data, and querying data.
If you use soft references then the garbage collector will defer collection of application objects until it determines that it needs the memory. In contrast the garbage collector ignores the presence of weak references when deciding whether or not to clear the references for an object. The backing LRU cache policy MUST be using hard references, so in any case nothing will be removed from the weak value cache until it has been first evicted from the backing LRU.
Finalizers MUST NOT be relied on to effect the persistent state of objects in this cache since (a) finalizers may never run; and (b) finalizers will only run after references to the object in the cache have been cleared.
Since dirty objects that are evicted from the hard reference cache are
installed on the database, it is NOT possible to have an object in the weak
cache that is (a) dirty; and (b) not also in the hard reference cache.
Therefore the dirty flag is only maintained by the hard
reference cache. When an object no longer exists in the hard reference cache
but it still present in the weak reference cache, a #get(long) will
cause the object to be installed into the hard reference cache and the object
will be marked as clean.
This implementation is synchronized.
| Modifier and Type | Class and Description |
|---|---|
static interface |
WeakValueCache.IClearReferenceListener<K>
An optional listener that is invoked when we notice a cleared reference.
|
| Modifier and Type | Field and Description |
|---|---|
protected static boolean |
DEBUG
True iff the
log level is DEBUG or less. |
protected static boolean |
INFO
True iff the
log level is INFO or less. |
static int |
INITIAL_CAPACITY
Default value for the initial capacity (1000).
|
static float |
LOAD_FACTOR
Default value for the load factor (0.75).
|
protected static org.apache.log4j.Logger |
log |
| Constructor and Description |
|---|
WeakValueCache(ICachePolicy<K,T> delegate) |
WeakValueCache(ICachePolicy<K,T> delegate,
IWeakRefCacheEntryFactory<K,T> factory) |
WeakValueCache(int initialCapacity,
float loadFactor,
ICachePolicy<K,T> delegate,
IWeakRefCacheEntryFactory<K,T> factory)
Designated constructor.
|
WeakValueCache(int initialCapacity,
float loadFactor,
ICachePolicy<K,T> delegate,
IWeakRefCacheEntryFactory<K,T> factory,
WeakValueCache.IClearReferenceListener<K> clearReferenceListener) |
| Modifier and Type | Method and Description |
|---|---|
int |
capacity()
The capacity of the backing hard reference cache.
|
void |
clear()
Clear all objects from the cache.
|
Iterator<ICacheEntry<K,T>> |
entryIterator()
Visits entries in the delegate cache in the order defined by the
delegate.
|
protected void |
finalize()
This reports some statistics gathered during the cache use.
|
T |
get(K oid)
Return the indicated object from the cache or null if the object is not
in cache.
|
ICacheListener<K,T> |
getCacheListener()
Return the listener on the delegate.
|
ICachePolicy<K,T> |
getDelegate()
The delegate hard reference cache.
|
Iterator<T> |
iterator()
Visits objects in the delegate cache in the order defined by the
delegate.
|
void |
put(K oid,
T obj,
boolean dirty)
Insert or "touch" this object in the cache.
|
T |
remove(K oid)
Remove the indicated object from the cache.
|
void |
reportStatistics(boolean resetCounters)
Report and optionally clear the cache statistics.
|
void |
setListener(ICacheListener<K,T> listener)
Sets the listener on the delegate.
|
int |
size()
The #of entries in the backing hard reference cache.
|
protected static final org.apache.log4j.Logger log
protected static final boolean INFO
log level is INFO or less.protected static final boolean DEBUG
log level is DEBUG or less.public static final int INITIAL_CAPACITY
public static final float LOAD_FACTOR
public WeakValueCache(ICachePolicy<K,T> delegate)
public WeakValueCache(ICachePolicy<K,T> delegate, IWeakRefCacheEntryFactory<K,T> factory)
public WeakValueCache(int initialCapacity,
float loadFactor,
ICachePolicy<K,T> delegate,
IWeakRefCacheEntryFactory<K,T> factory)
initialCapacity - May be used to reduce re-hashing by starting with a larger
initial capacity in the HashMap with weak values.
(The capacity of the delegate hard reference cache map is
configured separately.)loadFactor - May be used to bias for speed vs space in the HashMap.delegate - The delegate which MUST implement a hard reference cache
policy such as LRU.factory - The factory which will generate the weak reference value
objects for this cache.IllegalArgumentException - if the initialCapacity is negative.IllegalArgumentException - if the loadFactor is non-positive.public WeakValueCache(int initialCapacity,
float loadFactor,
ICachePolicy<K,T> delegate,
IWeakRefCacheEntryFactory<K,T> factory,
WeakValueCache.IClearReferenceListener<K> clearReferenceListener)
public ICachePolicy<K,T> getDelegate()
public void clear()
ICachePolicyclear in interface ICachePolicy<K,T>public void reportStatistics(boolean resetCounters)
resetCounters - When true the counters will be reset to zero.protected void finalize()
throws Throwable
public void put(K oid, T obj, boolean dirty)
ICachePolicyput in interface ICachePolicy<K,T>oid - The object identifier.obj - The object.dirty - True iff the object is dirty.public T get(K oid)
ICachePolicyget in interface ICachePolicy<K,T>oid - The object identifier.public T remove(K oid)
ICachePolicyremove in interface ICachePolicy<K,T>oid - The object identifier.null if there was no object under that identifier.public void setListener(ICacheListener<K,T> listener)
setListener in interface ICachePolicy<K,T>listener - The listener or null to remove any listener.public ICacheListener<K,T> getCacheListener()
getCacheListener in interface ICachePolicy<K,T>public Iterator<T> iterator()
Visits objects in the delegate cache in the order defined by the delegate.
Note: Objects evicted from the hard reference cache that are still weakly reachable are no longer accessible from the weak cache iterators. This is consistent with the policy that dirty objects are installed onto pages in the persistence layer when they are evicted from the inner hard reference cache and provides a fast iterator mechanism for scanning the object cache. While it means that you are not able to fully enumerate the entries in the weak reference cache, when integrated with a persistence layer handling installation of dirty objects onto pages, objects that are not visitable are guaranteed to be clean.
Note: While the iterator supports removal, its behavior is delegated to
the backing hard reference cache. Therefore, removal causes the entry to
be removed from the backing hard reference cache but NOT the
WeakValueCache. In order to remove the entry from the
WeakValueCache as well you can use entryIterator() and
then also delete the entry under the last visited key.
iterator in interface ICachePolicy<K,T>ICachePolicy.entryIterator()public Iterator<ICacheEntry<K,T>> entryIterator()
Visits entries in the delegate cache in the order defined by the delegate.
Note: Objects evicted from the hard reference cache that are still weakly reachable are no longer accessible from the weak cache iterators. This is consistent with the policy that dirty objects are installed onto pages in the persistence layer when they are evicted from the inner hard reference cache and provides a fast iterator mechanism for scanning the object cache. While it means that you are not able to fully enumerate the entries in the weak reference cache, when integrated with a persistence layer handling installation of dirty objects onto pages, entries that are not visitable are guaranteed to be clean.
Note: While the iterator supports removal, its behavior is delegated to
the backing hard reference cache. Therefore, removal causes the entry to
be removed from the backing hard reference cache but NOT the
WeakValueCache. In order to remove the entry from the
WeakValueCache you MUST also delete the entry under the last
visited key.
entryIterator in interface ICachePolicy<K,T>ICacheEntry objects from the delegate
hard reference cache.ICacheEntry,
ICachePolicy.iterator()public int size()
iterator()
or entryIterator().size in interface ICachePolicy<K,T>ICachePolicypublic int capacity()
capacity in interface ICachePolicy<K,T>Copyright © 2006–2019 SYSTAP, LLC DBA Blazegraph. All rights reserved.