Class CompositeCache

ICache implementation that wraps two caches - a front cache (assumed to be "inexpensive" and probably "incomplete") and a back cache (assumed to be "complete" and "correct", but more "expensive") - using a read-through/write-through approach.

Inheritance

object

CompositeCache

NearCache

Implements

Inherited Members

object.Equals(object, object)

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Namespace: Tangosol.Net.Cache

Assembly: Coherence.dll

Syntax

public class CompositeCache : ICache, IDictionary, ICollection, IEnumerable, ICacheStatistics, IDisposable

Remarks

If the back cache implements IObservableCache interface, the CompositeCache provides four different strategies of invalidating the front cache entries that have changed by other processes in the back cache:

ListenNone strategy instructs the cache not to listen for invalidation events at all. This is the best choice for raw performance and scalability when business requirements permit the use of data which might not be absolutely current. Freshness of data can be guaranteed by use of a sufficiently brief eviction policy for the front cache.
ListenPresent strategy instructs the CompositeCache to listen to the back cache events related only to the items currently present in the front cache. This strategy works best when each instance of a front cache contains distinct subset of data relative to the other front cache instances (e.g. sticky data access patterns).
ListenAll strategy instructs the CompositeCache to listen to all back cache events. This strategy is optimal for read-heavy tiered access patterns where there is significant overlap between the different instances of front caches.
ListenAuto strategy instructs the CompositeCache implementation to switch automatically between ListenPresent and ListenAll strategies based on the cache statistics.
ListenLogical strategy instructs the CompositeCache to listen to all back map events that are not synthetic. A synthetic event could be emitted as a result of eviction or expiration. With this invalidation stategy, it is possible for the front map to contain cache entries that have been synthetically removed from the back (though any subsequent re-insertion will cause the corresponding entries in the front map to be invalidated).

The front cache implementation is assumed to be thread safe; additionally any modifications to the front cache are allowed only after the corresponding lock is acquired against the CacheControl property.

Note: null values are not cached in the front cache and therefore this implementation is not optimized for caches that allow null values to be stored.

Constructors

CompositeCache(ICache, ICache)

Construct a CompositeCache using two specified caches:

FrontCache (aka "cache", "near" or "shallow")
BackCache (aka "actual", "real" or "deep")

Declaration

public CompositeCache(ICache front, ICache back)

Parameters

Type	Name	Description
ICache	front	The front cache.
ICache	back	The back cache.

Remarks

If the BackCache implements the IObservableCache interface a listener will be added to the BackCache to invalidate FrontCache items updated [externally] in the back cache using the ListenAuto strategy.

CompositeCache(ICache, ICache, CompositeCacheStrategyType)

Construct a CompositeCache using two specified caches:

FrontCache (aka "cache", "near" or "shallow")
BackCache (aka "actual", "real" or "deep")

and using the specified front cache invalidation strategy.

Declaration

public CompositeCache(ICache front, ICache back, CompositeCacheStrategyType strategy)

Parameters

Type	Name	Description
ICache	front	The front cache.
ICache	back	The back cache.
CompositeCacheStrategyType	strategy	Specifies the strategy used for the front caches invalidation; valid values are CompositeCacheStrategyType values.

Fields

m_strategyCurrent

The current invalidation strategy, which at times could be different from the target strategy.

Declaration

protected CompositeCacheStrategyType m_strategyCurrent

Field Value

Type	Description
CompositeCacheStrategyType

m_strategyTarget

The invalidation strategy that this cache is to use.

Declaration

protected CompositeCacheStrategyType m_strategyTarget

Field Value

Type	Description
CompositeCacheStrategyType

s_tloKeys

The ThreadLocal to hold all the keys that are evicted while the front cache is updated during get or getAll operation.

Declaration

protected static ThreadLocal<HashSet> s_tloKeys

Field Value

Type	Description
ThreadLocal<HashSet>

Properties

AverageGetMillis

Determine the average number of milliseconds per "get" invocation since the cache statistics were last reset.

Declaration

public virtual double AverageGetMillis { get; }

Property Value

Type	Description
double	The average number of milliseconds per "get" operation.

AverageHitMillis

Determine the average number of milliseconds per "get" invocation that is a hit.

Declaration

public virtual double AverageHitMillis { get; }

Property Value

Type	Description
double	The average number of milliseconds per cache hit.

AverageMissMillis

Determine the average number of milliseconds per "get" invocation that is a miss.

Declaration

public virtual double AverageMissMillis { get; }

Property Value

Type	Description
double	The average number of milliseconds per cache miss.

AveragePruneMillis

Determine the average number of milliseconds per cache pruning.

Declaration

public double AveragePruneMillis { get; }

Property Value

Type	Description
double	The average number of milliseconds per cache pruning.

AveragePutMillis

Determine the average number of milliseconds per "put" invocation since the cache statistics were last reset.

Declaration

public virtual double AveragePutMillis { get; }

Property Value

Type	Description
double	The average number of milliseconds per "put" operation.

BackCache

Obtain the back cache reference.

Declaration

public virtual ICache BackCache { get; }

Property Value

Type	Description
ICache	The back ICache.

Remarks

Note: direct modifications of the returned cache may cause an unpredictable behavior of the CompositeCache.

CacheControl

Obtain the IConcurrentCache that should be used to synchronize the front cache modification access.

Declaration

public virtual IConcurrentCache CacheControl { get; }

Property Value

Type	Description
IConcurrentCache	An IConcurrentCache instance controlling the front cache modifications.

CacheHits

Determine the rough number of cache hits since the cache statistics were last reset.

Declaration

public virtual long CacheHits { get; }

Property Value

Type	Description
long	The number of "get" calls that have been served by existing cache entries.

Remarks

A cache hit is a read operation invocation (i.e. "get") for which an entry exists in this cache.

CacheHitsMillis

Determine the total number of milliseconds (since that last statistics reset) for the "get" operations for which an entry existed in this cache.

Declaration

public virtual long CacheHitsMillis { get; }

Property Value

Type	Description
long	The total number of milliseconds for the "get" operations that were hits.

CacheMisses

Determine the rough number of cache misses since the cache statistics were last reset.

Declaration

public virtual long CacheMisses { get; }

Property Value

Type	Description
long	The number of "get" calls that failed to find an existing cache entry because the requested key was not in the cache.

Remarks

A cache miss is a "get" invocation that does not have an entry in this cache.

CacheMissesMillis

Determine the total number of milliseconds (since that last statistics reset) for the "get" operations for which no entry existed in this map.

Declaration

public virtual long CacheMissesMillis { get; }

Property Value

Type	Description
long	The total number of milliseconds (since that last statistics reset) for the "get" operations that were misses.

CachePrunes

Determine the rough number of cache pruning cycles since the cache statistics were last reset.

Declaration

public long CachePrunes { get; }

Property Value

Type	Description
long	The total number of cache pruning cycles (since that last statistics reset).

Remarks

For the LocalCache implementation, this refers to the number of times that the prune() method is executed.

CachePrunesMillis

Determine the total number of milliseconds (since that last statistics reset) spent on cache pruning.

Declaration

public long CachePrunesMillis { get; }

Property Value

Type	Description
long	The total number of milliseconds (since that last statistics reset) for cache pruning operations.

Remarks

For the LocalCache implementation, this refers to the time spent in the prune() method.

CacheStatistics

Obtain the CacheStatistics for this cache.

Declaration

public virtual ICacheStatistics CacheStatistics { get; }

Property Value

Type	Description
ICacheStatistics	A CacheStatistics object.

Count

Gets the number of elements contained in the BackCache.

Declaration

public virtual int Count { get; }

Property Value

Type	Description
int	The number of elements contained in the back cache.

Entries

Gets a collection of ICacheEntry instances within the cache.

Declaration

public virtual ICollection Entries { get; }

Property Value

Type	Description
ICollection

FrontCache

Obtain the front cache reference.

Declaration

public virtual ICache FrontCache { get; }

Property Value

Type	Description
ICache	The front ICache.

Remarks

Note: direct modifications of the returned cache may cause an unpredictable behavior of the CompositeCache.

HitProbability

Determine the rough probability (0 <= p <= 1) that the next invocation will be a hit, based on the statistics collected since the last reset of the cache statistics.

Declaration

public virtual double HitProbability { get; }

Property Value

Type	Description
double	The cache hit probability (0 <= p <= 1).

InvalidationHits

Determine the rough number of front cache invalidation hits since the cache statistics were last reset.

Declaration

public virtual long InvalidationHits { get; }

Property Value

Type	Description
long	The number of cache invalidation hits.

Remarks

An invalidation hit is an externally induced cache event for an entry that exists in the front cache.

InvalidationMisses

Determine the rough number of front cache invalidation misses since the cache statistics were last reset.

Declaration

public virtual long InvalidationMisses { get; }

Property Value

Type	Description
long	The number of cache invalidation misses.

Remarks

An invalidation hit is an externally induced cache event for an entry that exists in the front cache.

InvalidationStrategy

Obtain the invalidation strategy used by this CompositeCache.

Declaration

public virtual CompositeCacheStrategyType InvalidationStrategy { get; }

Property Value

Type	Description
CompositeCacheStrategyType	One of CompositeCacheStrategyType values.

IsCoherent

Determine if changes to the back cache affect the front cache so that data in the front cache stays in sync.

Declaration

protected virtual bool IsCoherent { get; }

Property Value

Type	Description
bool	`true` if the front cache has a means to stay in sync with the back cache so that it does not contain stale data.

IsFixedSize

Gets a value indicating whether the BackCache object has a fixed size.

Declaration

public virtual bool IsFixedSize { get; }

Property Value

Type	Description
bool	true if the BackCache object has a fixed size; otherwise, false.

IsReadOnly

Gets a value indicating whether the BackCache object is read-only.

Declaration

public virtual bool IsReadOnly { get; }

Property Value

Type	Description
bool	true if the BackCache object is a read-only; otherwise, false.

IsSynchronized

Gets a value indicating whether access to the back cache is synchronized (thread safe).

Declaration

public virtual bool IsSynchronized { get; }

Property Value

Type	Description
bool	true if access to the back cache is synchronized (thread safe); otherwise, false.

this[object]

Gets or sets the element with the specified key.

Declaration

public virtual object this[object key] { get; set; }

Parameters

Type	Name	Description
object	key	The key of the element to get or set.

Property Value

Type	Description
object	The element with the specified key.

Keys

Obtain an ICollection of the keys contained in this cache.

Declaration

public virtual ICollection Keys { get; }

Property Value

Type	Description
ICollection	An ICollection of the keys contained in this cache.

Remarks

If there is a listener for the back cache, then the collection will be mutable; otherwise the returned collection will be immutable. The returned collection reflects the full contents of the back cache.

SyncRoot

Gets an object that can be used to synchronize access to the back cache.

Declaration

public virtual object SyncRoot { get; }

Property Value

Type	Description
object	An object that can be used to synchronize access to the back cache.

TotalGets

Determine the total number of "get" operations since the cache statistics were last reset.

Declaration

public virtual long TotalGets { get; }

Property Value

Type	Description
long	The total number of "get" operations.

TotalGetsMillis

Determine the total number of milliseconds spent on "get" operations since the cache statistics were last reset.

Declaration

public virtual long TotalGetsMillis { get; }

Property Value

Type	Description
long	The total number of milliseconds processing "get" operations.

TotalPuts

Determine the total number of "put" operations since the cache statistics were last reset.

Declaration

public virtual long TotalPuts { get; }

Property Value

Type	Description
long	The total number of "put" operations.

TotalPutsMillis

Determine the total number of milliseconds spent on "put" operations since the cache statistics were last reset.

Declaration

public virtual long TotalPutsMillis { get; }

Property Value

Type	Description
long	The total number of milliseconds processing "put" operations.

TotalRegisterListener

Determine the total number of RegisterListener(object) operations since the cache statistics were last reset.

Declaration

public virtual long TotalRegisterListener { get; }

Property Value

Type	Description
long	The total number of listener registrations.

Values

Obtain an ICollection of the values contained in this cache.

Declaration

public virtual ICollection Values { get; }

Property Value

Type	Description
ICollection	An ICollection of the values contained in this cache.

Remarks

Methods

Add(object, object)

Associates the specified value with the specified key in this cache.

Declaration

public virtual void Add(object key, object value)

Parameters

Type	Name	Description
object	key	Key with which the specified value is to be associated.
object	value	Value to be associated with the specified key.

Clear()

Clears both the front and back caches.

Declaration

public virtual void Clear()

Contains(object)

Check whether or not this cache contains a mapping for the specified key.

Declaration

public virtual bool Contains(object key)

Parameters

Type	Name	Description
object	key	The key.

Returns

Type	Description
bool	true if this cache contains a mapping for the specified key, false otherwise.

CopyTo(Array, int)

Copies the elements of the BackCache to an Array, starting at a particular Array index.

Declaration

public virtual void CopyTo(Array array, int index)

Parameters

Type	Name	Description
Array	array	The one-dimensional Array that is the destination of the elements copied from BackCache. The Array must have zero-based indexing.
int	index	The zero-based index in array at which copying begins.

Dispose()

Calls Release() to release the resources associated with this cache.

Declaration

public void Dispose()

EnsureInvalidationStrategy()

Ensure that a strategy has been choosen and that any appropriate global listeners have been registered.

Declaration

protected virtual CompositeCacheStrategyType EnsureInvalidationStrategy()

Returns

Type	Description
CompositeCacheStrategyType	The current strategy.

Equals(object)

Compares the specified object with this dictionary for equality.

Declaration

public override bool Equals(object o)

Parameters

Type	Name	Description
object	o	Object to be compared for equality with this dictionary.

Returns

Type	Description
bool	true if the specified object is equal to this dictionary.

Overrides

object.Equals(object)

GetAll(ICollection)

Get the values for all the specified keys, if they are in the cache.

Declaration

public virtual IDictionary GetAll(ICollection keys)

Parameters

Type	Name	Description
ICollection	keys	A collection of keys that may be in the named cache.

Returns

Type	Description
IDictionary	A dictionary of keys to values for the specified keys passed in `keys`.

Remarks

For each key that is in the cache, that key and its corresponding value will be placed in the dictionary that is returned by this method. The absence of a key in the returned dictionary indicates that it was not in the cache, which may imply (for caches that can load behind the scenes) that the requested data could not be loaded.

Note: this implementation does not differentiate between missing keys or null values stored in the back dictionary; in both cases the returned dictionary will not contain the corresponding entry.

GetEnumerator()

Returns an enumerator that iterates through a cache.

Declaration

public virtual IEnumerator GetEnumerator()

Returns

Type	Description
IEnumerator	An IEnumerator object that can be used to iterate through the back cache.

GetHashCode()

Return the hash code value for this dictionary.

Declaration

public override int GetHashCode()

Returns

Type	Description
int	The hash code value for this dictionary.

Overrides

object.GetHashCode()

Insert(object, object)

Associates the specified value with the specified key in this cache.

Declaration

public virtual object Insert(object key, object value)

Parameters

Type	Name	Description
object	key	Key with which the specified value is to be associated.
object	value	Value to be associated with the specified key.

Returns

Type	Description
object	Previous value associated with specified key, or `null` if there was no mapping for key. A `null` return can also indicate that the dictionary previously associated `null` with the specified key, if the implementation supports `null` values.

Remarks

If the cache previously contained a mapping for this key, the old value is replaced.

Invoking this method is equivalent to the following call:

Insert(key, value, CacheExpiration.Default);

Insert(object, object, long)

Associates the specified value with the specified key in this cache.

Declaration

public virtual object Insert(object key, object value, long millis)

Parameters

Type	Name	Description
object	key	Key with which the specified value is to be associated.
object	value	Value to be associated with the specified key.
long	millis	The number of milliseconds until the cache entry will expire, also referred to as the entry's "time to live"; pass DEFAULT to use the cache's default time-to-live setting; pass NEVER to indicate that the cache entry should never expire; this milliseconds value is not a date/time value, but the amount of time object will be kept in the cache.

Returns

Type	Description
object	Previous value associated with specified key, or `null` if there was no mapping for key. A `null` return can also indicate that the cache previously associated `null` with the specified key, if the implementation supports `null` values.

Remarks

If the cache previously contained a mapping for this key, the old value is replaced.

This variation of the Insert(object, object) method allows the caller to specify an expiry (or "time to live") for the cache entry.

Exceptions

Type	Condition
NotSupportedException	If the requested expiry is a positive value and the implementation does not support expiry of cache entries.

InsertAll(IDictionary)

Copies all of the mappings from the specified dictionary to this cache (optional operation).

Declaration

public virtual void InsertAll(IDictionary dictionary)

Parameters

Type	Name	Description
IDictionary	dictionary	Mappings to be stored in this cache.

Remarks

These mappings will replace any mappings that this cache had for any of the keys currently in the specified dictionary.

Exceptions

Type	Condition
InvalidCastException	If the class of a key or value in the specified dictionary prevents it from being stored in this cache.
InvalidOperationException	If the lock could not be succesfully obtained for some key.
NullReferenceException	This cache does not permit `null` keys or values, and the specified key or value is `null`.

InstantiateBackCacheListener(CompositeCacheStrategyType)

Factory pattern: instantiate back cache listener.

Declaration

protected virtual ICacheListener InstantiateBackCacheListener(CompositeCacheStrategyType strategy)

Parameters

Type	Name	Description
CompositeCacheStrategyType	strategy	CompositeCacheStrategyType.

Returns

Type	Description
ICacheListener	An instance of back cache listener responsible for keeping the front cache coherent with the back cache.

InstantiateFrontCacheListener()

Factory pattern: instantiate front cache listener.

Declaration

protected virtual CompositeCache.FrontCacheListener InstantiateFrontCacheListener()

Returns

Type	Description
CompositeCache.FrontCacheListener	An instance of front cache listener.

InvalidateFront(object)

Invalidate the key from the front.

Declaration

protected virtual void InvalidateFront(object key)

Parameters

Type	Name	Description
object	key	The key to invalidate.

Remarks

The caller must have the key locked.

IsPriming(CacheEventArgs)

Check if the specified event is a "priming" one.

Declaration

protected static bool IsPriming(CacheEventArgs evt)

Parameters

Type	Name	Description
CacheEventArgs	evt	CacheEvent to check.

Returns

Type	Description
bool	true iff the event is a Priming Event.

RegisterDeactivationListener()

Instantiate and register a DeactivationListener with the back cache.

Declaration

protected virtual void RegisterDeactivationListener()

RegisterFrontListener()

Declaration

protected virtual void RegisterFrontListener()

RegisterListener()

Declaration

protected virtual void RegisterListener()

RegisterListener(object)

Declaration

protected virtual void RegisterListener(object key)

Parameters

Type	Name	Description
object	key	The key.

RegisterListeners(HashSet)

Declaration

protected virtual void RegisterListeners(HashSet setKeys)

Parameters

Type	Name	Description
HashSet	setKeys	The key set.

Release()

Release the CompositeCache.

Declaration

public virtual void Release()

Remarks

If the ICache implements an IObservableCache calling this method is necessary to remove the back cache listener. Any access to the CompositeCache which has been released will cause InvalidOperationException.

Remove(object)

Remove the mapping for this key from this cache if present.

Declaration

public virtual void Remove(object key)

Parameters

Type	Name	Description
object	key	Key whose mapping is to be removed from the cache.

Remarks

Expensive: updates both the underlying cache and the local cache.

RemoveKeyHolder()

Remove the key holder from the ThreadLocal object.

Declaration

protected void RemoveKeyHolder()

ResetFrontMap()

Reset the front map.

Declaration

public void ResetFrontMap()

ResetHitStatistics()

Reset the cache statistics.

Declaration

public virtual void ResetHitStatistics()

ResetInvalidationStrategy()

Reset the "current invalidation strategy" flag.

Declaration

protected virtual void ResetInvalidationStrategy()

Remarks

This method should be called only while the access to the front cache is fully synchronzied and the front cache is empty to prevent stalled data.

SetKeyHolder()

Set up a thread local Set to hold all the keys that might be evicted from the front cache.

Declaration

protected HashSet SetKeyHolder()

Returns

Type	Description
HashSet	a Set to hold all the keys in the ThreadLocal object or null if the bulk unregistering is not needed.

ToString()

For debugging purposes, format the contents of the CompositeCache in a human readable format.

Declaration

public override string ToString()

Returns

Type	Description
string	A String representation of the CompositeCache object.

Overrides

object.ToString()

TryLock(HashSet)

Lock the keys in the given set without blocking.

Declaration

protected virtual HashSet TryLock(HashSet setKeys)

Parameters

Type	Name	Description
HashSet	setKeys	keys to lock in the control map.

Returns

Type	Description
HashSet	Set of keys that were successfully locked.

UnregisterDeactivationListener()

Unregister back cache deactivation listener.

Declaration

protected void UnregisterDeactivationListener()

UnregisterFrontListener()

Unregister the global front cache listener.

Declaration

protected virtual void UnregisterFrontListener()

UnregisterListener()

Unregister the global back cache listener.

Declaration

protected virtual void UnregisterListener()

UnregisterListener(object)

Unregister the back cache listener for the specified key.

Declaration

protected virtual void UnregisterListener(object key)

Parameters

Type	Name	Description
object	key	The key.

UnregisterListeners(ICollection)

Unregister the back cache listener for the specified keys.

Note: all the keys in the passed-in set must be locked and will be unlocked.

Declaration

protected virtual void UnregisterListeners(ICollection setKeys)

Parameters

Type	Name	Description
ICollection	setKeys	Set of keys to unregister (and unlock).

Validate(CacheEventArgs)

Validate the front cache entry for the specified back cache event.

Declaration

protected virtual void Validate(CacheEventArgs evt)

Parameters

Type	Name	Description
CacheEventArgs	evt	The CacheEventArgs from the back cache.

Implements

ICache

IDictionary

ICollection

IEnumerable

ICacheStatistics

IDisposable