com.bigdata.cache
Class WeakValueCache<K,T>

java.lang.Object
  com.bigdata.cache.WeakValueCache<K,T>

All Implemented Interfaces:

ICachePolicy<K,T>

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.

Version:

$Id: WeakValueCache.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

thompsonbry

TODO:

Consider removing synchronization for use in a single threaded context.

Nested Class Summary

static interface

WeakValueCache.IClearReferenceListener<K> An optional listener that is invoked when we notice a cleared reference.

Field Summary

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 Summary

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)

Method Summary

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.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

log

protected static final org.apache.log4j.Logger log

INFO

protected static final boolean INFO

True iff the log level is INFO or less.

DEBUG

protected static final boolean DEBUG

True iff the log level is DEBUG or less.

INITIAL_CAPACITY

public static final int INITIAL_CAPACITY

Default value for the initial capacity (1000).

See Also:

Constant Field Values

LOAD_FACTOR

public static final float LOAD_FACTOR

Default value for the load factor (0.75).

See Also:

Constant Field Values

Constructor Detail

WeakValueCache

public WeakValueCache(ICachePolicy<K,T> delegate)

WeakValueCache

public WeakValueCache(ICachePolicy<K,T> delegate,
                      IWeakRefCacheEntryFactory<K,T> factory)

WeakValueCache

public WeakValueCache(int initialCapacity,
                      float loadFactor,
                      ICachePolicy<K,T> delegate,
                      IWeakRefCacheEntryFactory<K,T> factory)

Designated constructor.

Parameters:

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.

Throws:

IllegalArgumentException - if the initialCapacity is negative.

IllegalArgumentException - if the loadFactor is non-positive.

WeakValueCache

public WeakValueCache(int initialCapacity,
                      float loadFactor,
                      ICachePolicy<K,T> delegate,
                      IWeakRefCacheEntryFactory<K,T> factory,
                      WeakValueCache.IClearReferenceListener<K> clearReferenceListener)

Method Detail

getDelegate

public ICachePolicy<K,T> getDelegate()

The delegate hard reference cache.

clear

public void clear()

Description copied from interface: ICachePolicy

Clear all objects from the cache. This method may be used to reset the cache when a transaction is being rolled back. Cache eviction notices are NOT fired when this method is called.

Specified by:

clear in interface ICachePolicy<K,T>

reportStatistics

public void reportStatistics(boolean resetCounters)

Report and optionally clear the cache statistics.

Parameters:

resetCounters - When true the counters will be reset to zero.

TODO:

modify to use CounterSet.

finalize

protected void finalize()
                 throws Throwable

This reports some statistics gathered during the cache use. The execution of this finalizer is NOT required for the correct functioning of the cache.

Overrides:

finalize in class Object

Throws:

Throwable

put

public void put(K oid,
                T obj,
                boolean dirty)

Description copied from interface: ICachePolicy

Insert or "touch" this object in the cache.

Specified by:

put in interface ICachePolicy<K,T>

Parameters:

oid - The object identifier.

obj - The object.

dirty - True iff the object is dirty.

get

public T get(K oid)

Description copied from interface: ICachePolicy

Return the indicated object from the cache or null if the object is not in cache.

Specified by:

get in interface ICachePolicy<K,T>

Parameters:

oid - The object identifier.

Returns:

The object or null iff it is not in cache.

remove

public T remove(K oid)

Description copied from interface: ICachePolicy

Remove the indicated object from the cache.

Specified by:

remove in interface ICachePolicy<K,T>

Parameters:

oid - The object identifier.

Returns:

The object in the cache for that object identifier or null if there was no object under that identifier.

setListener

public void setListener(ICacheListener<K,T> listener)

Sets the listener on the delegate.

Specified by:

setListener in interface ICachePolicy<K,T>

Parameters:

listener - The listener or null to remove any listener.

getCacheListener

public ICacheListener<K,T> getCacheListener()

Return the listener on the delegate.

Specified by:

getCacheListener in interface ICachePolicy<K,T>

iterator

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.

Specified by:

iterator in interface ICachePolicy<K,T>

Returns:

Iterator visiting objects from the delegate hard reference cache.

See Also:

ICachePolicy.entryIterator()

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.

Specified by:

entryIterator in interface ICachePolicy<K,T>

Returns:

Iterator visiting ICacheEntry objects from the delegate hard reference cache.

See Also:

ICacheEntry, ICachePolicy.iterator()

size

public int size()

The #of entries in the backing hard reference cache. The weak reference cache will often contain additional entries, but those entries are not reported by this method and can not be visited by either iterator() or entryIterator().

Specified by:

size in interface ICachePolicy<K,T>

Returns:

The #of entries in the hard reference cache.

See Also:

ICachePolicy

capacity

public int capacity()

The capacity of the backing hard reference cache.

Specified by:

capacity in interface ICachePolicy<K,T>

Returns:

The capacity of the hard reference cache.