#include <coherence/net/cache/OldCache.hpp>
The implementation is thread safe and uses a combination of Most Recently Used (MRU) and Most Frequently Used (MFU) caching strategies.
The cache is size-limited, which means that once it reaches its maximum size ("high-water mark") it prunes itself (to its "low-water mark"). The cache high- and low-water-marks are measured in terms of "units", and each cached item by default uses one unit. All of the cache constructors, except for the default constructor, require the maximum number of units to be passed in. To change the number of units that each cache entry uses, either set the Units property of the cache entry, or extend the Cache implementation so that the inner Entry class calculates its own unit size. To determine the current, high-water and low-water sizes of the cache, use the cache object's Units, HighUnits and LowUnits properties. The HighUnits and LowUnits properties can be changed, even after the cache is in use. To specify the LowUnits value as a percentage when constructing the cache, use the extended constructor taking the percentage-prune-level.
Each cached entry expires after one hour by default. To alter this behavior, use a constructor that takes the expiry-millis; for example, an expiry-millis value of 10000 will expire entries after 10 seconds. The ExpiryDelay property can also be set once the cache is in use, but it will not affect the expiry of previously cached items.
The cache can optionally be flushed on a periodic basis by setting the FlushDelay property or scheduling a specific flush time by setting the FlushTime property.
Cache hit statistics can be obtained from the CacheHits, CacheMisses, HitProbability, KeyHitProbability and CompositeHitProbability read-only properties. The statistics can be reset by invoking resetHitStatistics. The statistics are automatically reset when the cache is cleared (the clear method).
The OldCache implements the ObservableMap interface, meaning it provides event notifications to any interested listener for each insert, update and delete, including those that occur when the cache is pruned or entries are automatically expired.
This implementation is designed to support extension through inheritence. When overriding the inner Entry class, the OldCache.instantiateEntry factory method must be overridden to instantiate the correct Entry sub-class. To override the one-unit-per-entry default behavior, extend the inner Entry class and override the calculateUnits method.
The C++ version of OldCache requires a call release(), in order for it to be collected. Not including a call to release will result in the OldCache being leaked.
Public Types | |
enum | UnitCalculatorType { unit_calculator_fixed, unit_calculator_external } |
Unit calculator configuration enum. More... | |
typedef spec::Handle | Handle |
OldCache Handle definition. | |
typedef spec::View | View |
OldCache View definition. | |
typedef spec::Holder | Holder |
OldCache Holder definition. | |
Public Member Functions | |
virtual SafeHashMap::Entry::Handle | instantiateEntry (Object::View vKey, Object::Holder ohValue, size32_t nHash) |
virtual SafeHashMap::Entry::Handle | instantiateEntry (SafeHashMap::Entry::View vThat) |
virtual void | addKeyListener (MapListener::Handle hListener, Object::View vKey, bool fLite) |
virtual void | removeKeyListener (MapListener::Handle hListener, Object::View vKey) |
virtual void | addMapListener (MapListener::Handle hListener) |
virtual void | removeMapListener (MapListener::Handle hListener) |
virtual void | addFilterListener (MapListener::Handle hListener, Filter::View vFilter=NULL, bool fLite=false) |
virtual void | removeFilterListener (MapListener::Handle hListener, Filter::View vFilter=NULL) |
virtual bool | isEmpty () const |
virtual size32_t | size () const |
virtual bool | containsKey (Object::View vKey) const |
virtual Object::Holder | get (Object::View vKey) const |
virtual Object::Holder | put (Object::View vKey, Object::Holder ohValue) |
virtual Object::Holder | remove (Object::View vKey) |
virtual void | clear () |
virtual Object::Holder | put (Object::View vKey, Object::Holder ohValue, int64_t cMillis) |
virtual Map::View | getAll (Collection::View vColKeys) const |
virtual void | release () |
Release local resources associated with the Cache. | |
virtual void | evict (Object::View vKey) |
Evict a specified key from the cache, as if it had expired from the cache. | |
virtual void | evictAll (Collection::View vColKeys) |
Evict the specified keys from the cache, as if they had each expired from the cache. | |
virtual void | evict () |
Evict all entries from the cache that are no longer valid, and potentially prune the cache size if the cache is size-limited and its size is above the caching low water mark. | |
virtual CacheStatistics::View | getCacheStatistics () const |
Returns the CacheStatistics for this cache. | |
virtual CacheStatistics::Handle | getCacheStatistics () |
Returns the CacheStatistics for this cache. | |
virtual size32_t | getUnits () const |
Determine the number of units that the cache currently stores. | |
virtual size32_t | getHighUnits () const |
Determine the limit of the cache size in units. | |
virtual void | setHighUnits (size32_t cMax) |
Update the maximum size of the cache in units. | |
virtual size32_t | getLowUnits () const |
Determine the point to which the cache will shrink when it prunes. | |
virtual void | setLowUnits (size32_t cUnits) |
Specify the point to which the cache will shrink when it prunes. | |
virtual EvictionPolicy::EvictionPolicyType | getEvictionType () const |
Determine the current eviction type. | |
virtual void | setEvictionType (EvictionPolicy::EvictionPolicyType nType) |
Specify the eviction type for the cache. | |
virtual EvictionPolicy::View | getEvictionPolicy () const |
Determine the current external eviction policy, if any. | |
virtual EvictionPolicy::Handle | getEvictionPolicy () |
Determine the current external eviction policy, if any. | |
virtual void | setEvictionPolicy (EvictionPolicy::Handle hPolicy) |
Set the external eviction policy, and change the eviction type to eviction_policy_external. | |
virtual UnitCalculatorType | getUnitCalculatorType () const |
Determine the current unit calculator type. | |
virtual void | setUnitCalculatorType (UnitCalculatorType nType) |
Specify the unit calculator type for the cache. | |
virtual UnitCalculator::View | getUnitCalculator () const |
Determine the current external unit calculator, if any. | |
virtual void | setUnitCalculator (UnitCalculator::Handle hCalculator) |
Set the external unit calculator, and change the unit calculator type to unit_calculator_external. | |
virtual int32_t | getExpiryDelay () const |
Determine the "time to live" for each individual cache entry. | |
virtual void | setExpiryDelay (int cMillis) |
Specify the "time to live" for cache entries. | |
virtual int32_t | getFlushDelay () const |
Determine the delay between cache flushes. | |
virtual void | setFlushDelay (int32_t cMillis) |
Specify the delay between cache flushes. | |
virtual int64_t | getFlushTime () const |
Determine the date/time at which the next cache flush is scheduled. | |
virtual void | setFlushTime (int64_t lMillis) |
Specify the date/time at which the next cache flush is to occur. | |
virtual void | setAllowMutableValues (bool fAllow) |
Specify if the cache is allowed to hold mutable values. | |
virtual bool | isAllowMutableValues () const |
Return whether the cache is allowed to hold mutable values. | |
virtual int64_t | getCacheHits () const |
Determine the rough number of cache hits since the cache statistics were last reset. | |
virtual int64_t | getCacheMisses () const |
Determine the rough number of cache misses since the cache statistics were last reset. | |
virtual float64_t | getHitProbability () const |
Determine the rough probability (0 <= p <= 1) that any particular get invocation will be satisfied by an existing entry in the cache, based on the statistics collected since the last reset of the cache statistics. | |
virtual void | resetHitStatistics () |
Reset the cache statistics. | |
virtual TypedHandle < const String > | toString () const |
virtual SafeHashMap::Entry::View | getEntry (Object::View vKey) const |
virtual SafeHashMap::Entry::Handle | getEntry (Object::View vKey) |
Static Public Member Functions | |
static float64_t | getDefaultPrune () |
By default, when the cache prunes, it reduces its entries by 25%, meaning it retains 75% (.75) of its entries. | |
Static Public Attributes | |
static const size32_t | default_units |
By default, the cache size (in units). | |
static const int32_t | default_expire |
By default, the cache entries expire after one hour. | |
static const int32_t | default_flush |
By default, expired cache entries are flushed on a minute interval. | |
Protected Member Functions | |
OldCache (size32_t cUnits=default_units, int32_t cExpiryMillis=default_expire, float64_t dflPruneLevel=0.75F, size32_t cInitialBuckets=17, float32_t flLoadFactor=1.0F, float32_t flGrowthRate=3.0F) | |
Construct an instanceo of OldCache. | |
virtual Set::Handle | instantiateEntrySet () |
virtual Set::View | instantiateEntrySet () const |
virtual Set::Handle | instantiateKeySet () |
virtual Set::View | instantiateKeySet () const |
virtual Collection::Handle | instantiateValuesCollection () |
virtual Collection::View | instantiateValuesCollection () const |
virtual void | configureEviction (EvictionPolicy::EvictionPolicyType nType, EvictionPolicy::Handle hPolicy) |
Configure the eviction type and policy. | |
virtual void | configureUnitCalculator (UnitCalculatorType nType, UnitCalculator::Handle hCalculator) |
Configure the unit calculator type and implementation. | |
virtual SafeHashMap::Entry::Handle | getEntryInternal (Object::View vKey) const |
Locate an Entry in the hash map based on its key. | |
virtual void | checkFlush () const |
Check if the cache is timed out, and clear if it is. | |
virtual void | checkFlush () |
Check if the cache is timed out, and clear if it is. | |
virtual void | removeExpired (Entry::View vEntry, bool fRemoveInternal) const |
Remove an entry because it has expired. | |
virtual void | removeExpired (Entry::Handle hEntry, bool fRemoveInternal) |
Remove an entry because it has expired. | |
virtual void | incrementUnits (size32_t cDelta) |
Increment the current size. | |
virtual void | decrementUnits (size32_t cDelta) |
Decrement the current size. | |
virtual void | checkSize () |
Check if the cache is too big, and if it is prune it by discarding the lowest priority cache entries. | |
virtual void | prune () |
Prune the cache by discarding the lowest priority cache entries. | |
virtual void | deferFlush () |
Defer the next flush by scheduling it for infinity and beyond. | |
virtual void | scheduleFlush () |
Schedule the next flush. | |
virtual MapEvent::Handle | instantiateMapEvent (int32_t nId, Object::View vKey, Object::Holder ohValueOld, Object::Holder ohValueNew) |
Factory pattern: instantiate a new MapEvent corresponding to the specified parameters. | |
virtual MapListenerSupport::Handle | getMapListenerSupport () |
Accessor for the MapListenerSupport for sub-classes. | |
virtual bool | hasListeners () |
Determine if the OverflowMap has any listeners at all. | |
virtual void | dispatchEvent (MapEvent::Handle hEvt) |
Dispatch the passed event. | |
Protected Attributes | |
size32_t | m_cCurUnits |
The current number of units in the cache. | |
size32_t | m_cMaxUnits |
The number of units to allow the cache to grow to before pruning. | |
float64_t | m_dflPruneLevel |
The percentage of the total number of units that will remain after the cache manager prunes the cache (i.e. | |
size32_t | m_cPruneUnits |
The number of units to prune the cache down to. | |
size32_t | m_cExpiryDelay |
The number of milliseconds that a value will live in the cache. | |
int32_t | m_cFlushDelay |
The interval between full cache flushes, in milliseconds. | |
Volatile< int64_t > | m_lNextFlush |
The time (ie System.currentTimeMillis) at which the next full cache flush should occur. | |
FinalHandle < SimpleCacheStatistics > | f_hStats |
The CacheStatistics object maintained by this cache. | |
MemberHandle < MapListenerSupport > | m_hListenerSupport |
The MapListenerSupport object. | |
EvictionPolicy::EvictionPolicyType | m_nEvictionType |
The type of eviction policy employed by the cache; one of the EVICTION_POLICY_* enumerated values. | |
MemberHandle < EvictionPolicy > | m_hPolicy |
The eviction policy; for eviction type eviction_policy_external. | |
UnitCalculatorType | m_CalculatorType |
The type of unit calculator employed by the cache; one of the UNIT_CALCULATOR_* enumerated values. | |
MemberView < UnitCalculator > | m_vCalculator |
The external unit calculator. | |
int64_t | m_lLastPrune |
The last time that a prune was run. | |
size32_t | m_cAvgTouch |
For a prune cycle, this value is the average number of touches that an entry should have. | |
bool | m_fAllowMutableValues |
Allow mutable values. | |
Classes | |
class | Entry |
Entry for the local cache extends SafeHashMap::Entry adding entry statistics used for the various eviction policies. More... | |
class | EntrySet |
A set of entries backed by this map. More... | |
class | IteratorFilter |
This iterator will filter out expired entries from the result set and expire them. More... | |
class | KeySet |
A set of entries backed by this map. More... | |
class | ValuesCollection |
A set of entries backed by this map. More... |
enum UnitCalculatorType |
OldCache | ( | size32_t | cUnits = default_units , |
|
int32_t | cExpiryMillis = default_expire , |
|||
float64_t | dflPruneLevel = 0.75F , |
|||
size32_t | cInitialBuckets = 17 , |
|||
float32_t | flLoadFactor = 1.0F , |
|||
float32_t | flGrowthRate = 3.0F | |||
) | [protected] |
Construct an instanceo of OldCache.
vsName | the Name of the cache to construct | |
cUnits | the number of units that the cache manager will cache before pruning the cache | |
cExpiryMillis | the number of milliseconds that each cache entry lives before being automatically expired | |
dflPruneLevel | the percentage of the total number of units that will remain after the cache manager prunes the cache (i.e. this is the "low water mark" value); this value is in the range 0.0 to 1.0 | |
cInitialBuckets | the initial number of hash buckets, 0 < n | |
flLoadFactor | the acceptable load factor before resizing occurs, 0 < n, such that a load factor of 1.0 causes resizing when the number of entries exceeds the number of buckets | |
flGrowthRate | the rate of bucket growth when a resize occurs, 0 < n, such that a growth rate of 1.0 will double the number of buckets: bucketcount = bucketcount * (1 + growthrate) |
virtual void release | ( | ) | [virtual] |
Release local resources associated with the Cache.
Releasing a cache makes it no longer usable
virtual void evict | ( | Object::View | vKey | ) | [virtual] |
virtual void evictAll | ( | Collection::View | vColKeys | ) | [virtual] |
Evict the specified keys from the cache, as if they had each expired from the cache.
The result of this method is defined to be semantically the same as the following implementation:
for (Iterator iter = colKeys.iterator(); iter.hasNext(); ) { Object oKey = iter.next(); evict(oKey); }
colKeys | a collection of keys to evict from the cache |
virtual CacheStatistics::View getCacheStatistics | ( | ) | const [virtual] |
Returns the CacheStatistics for this cache.
virtual CacheStatistics::Handle getCacheStatistics | ( | ) | [virtual] |
Returns the CacheStatistics for this cache.
virtual size32_t getUnits | ( | ) | const [virtual] |
virtual size32_t getHighUnits | ( | ) | const [virtual] |
virtual void setHighUnits | ( | size32_t | cMax | ) | [virtual] |
virtual size32_t getLowUnits | ( | ) | const [virtual] |
virtual void setLowUnits | ( | size32_t | cUnits | ) | [virtual] |
virtual EvictionPolicy::EvictionPolicyType getEvictionType | ( | ) | const [virtual] |
Determine the current eviction type.
virtual void setEvictionType | ( | EvictionPolicy::EvictionPolicyType | nType | ) | [virtual] |
Specify the eviction type for the cache.
The type can only be set to an external policy if an EvictionPolicy object has been provided.
nType | one of the EVICTION_POLICY_* enumerated values |
virtual EvictionPolicy::View getEvictionPolicy | ( | ) | const [virtual] |
Determine the current external eviction policy, if any.
virtual EvictionPolicy::Handle getEvictionPolicy | ( | ) | [virtual] |
Determine the current external eviction policy, if any.
virtual void setEvictionPolicy | ( | EvictionPolicy::Handle | hPolicy | ) | [virtual] |
Set the external eviction policy, and change the eviction type to eviction_policy_external.
If null is passed, clear the external eviction policy, and use the default internal policy.
policy | an external eviction policy, or null to use the default policy |
virtual UnitCalculatorType getUnitCalculatorType | ( | ) | const [virtual] |
Determine the current unit calculator type.
virtual void setUnitCalculatorType | ( | UnitCalculatorType | nType | ) | [virtual] |
Specify the unit calculator type for the cache.
The type can only be set to an external unit calculator if a UnitCalculator object has been provided.
nType | one of the UNIT_CALCULATOR_* enumerated values |
virtual UnitCalculator::View getUnitCalculator | ( | ) | const [virtual] |
Determine the current external unit calculator, if any.
virtual void setUnitCalculator | ( | UnitCalculator::Handle | hCalculator | ) | [virtual] |
Set the external unit calculator, and change the unit calculator type to unit_calculator_external.
If null is passed, clear the external unit calculator, and use the default unit calculator.
calculator | an external unit calculator, or null to use the default unit calculator |
virtual int32_t getExpiryDelay | ( | ) | const [virtual] |
virtual void setExpiryDelay | ( | int | cMillis | ) | [virtual] |
virtual int32_t getFlushDelay | ( | ) | const [virtual] |
virtual void setFlushDelay | ( | int32_t | cMillis | ) | [virtual] |
virtual int64_t getFlushTime | ( | ) | const [virtual] |
Determine the date/time at which the next cache flush is scheduled.
Note that the date/time may be Long.max_value, which implies that a flush will never occur. Also note that the cache may internally adjust the flush time to prevent a flush from occurring during certain processing as a means to raise concurrency.
virtual void setFlushTime | ( | int64_t | lMillis | ) | [virtual] |
Specify the date/time at which the next cache flush is to occur.
Note that the date/time may be Long.max_value, which implies that a flush will never occur. A time in the past or at the present will cause an immediate flush.
lMillis | the date/time value, in milliseconds, when the cache should next automatically flush |
virtual void setAllowMutableValues | ( | bool | fAllow | ) | [virtual] |
virtual bool isAllowMutableValues | ( | ) | const [virtual] |
virtual int64_t getCacheHits | ( | ) | const [virtual] |
virtual int64_t getCacheMisses | ( | ) | const [virtual] |
virtual float64_t getHitProbability | ( | ) | const [virtual] |
virtual void configureEviction | ( | EvictionPolicy::EvictionPolicyType | nType, | |
EvictionPolicy::Handle | hPolicy | |||
) | [protected, virtual] |
Configure the eviction type and policy.
nType | one of the EVICTION_POLICY_* enumerated values | |
hPolicy | an external eviction policy, or null |
virtual void configureUnitCalculator | ( | UnitCalculatorType | nType, | |
UnitCalculator::Handle | hCalculator | |||
) | [protected, virtual] |
Configure the unit calculator type and implementation.
nType | one of the UNIT_CALCULATOR_* enumerated values | |
hCalculator | an external unit calculator, or null |
virtual SafeHashMap::Entry::Handle getEntryInternal | ( | Object::View | vKey | ) | const [protected, virtual] |
Locate an Entry in the hash map based on its key.
If the Entry has expired, it is removed from the hash map.
Unlike the getEntry method, this method does not flush the cache (if necessary) or update cache statistics.
oKey | the key object to search for |
virtual void removeExpired | ( | Entry::View | vEntry, | |
bool | fRemoveInternal | |||
) | const [protected, virtual] |
virtual void removeExpired | ( | Entry::Handle | hEntry, | |
bool | fRemoveInternal | |||
) | [protected, virtual] |
virtual MapEvent::Handle instantiateMapEvent | ( | int32_t | nId, | |
Object::View | vKey, | |||
Object::Holder | ohValueOld, | |||
Object::Holder | ohValueNew | |||
) | [protected, virtual] |
Factory pattern: instantiate a new MapEvent corresponding to the specified parameters.
virtual MapListenerSupport::Handle getMapListenerSupport | ( | ) | [protected, virtual] |
Accessor for the MapListenerSupport for sub-classes.
virtual bool hasListeners | ( | ) | [protected, virtual] |
Determine if the OverflowMap has any listeners at all.
virtual void dispatchEvent | ( | MapEvent::Handle | hEvt | ) | [protected, virtual] |
Dispatch the passed event.
hEvt | a CacheEvent object |
size32_t m_cCurUnits [protected] |
float64_t m_dflPruneLevel [protected] |
size32_t m_cExpiryDelay [protected] |
The number of milliseconds that a value will live in the cache.
Zero indicates no timeout.
int64_t m_lLastPrune [protected] |
The last time that a prune was run.
This value is used by the hybrid eviction policy.
size32_t m_cAvgTouch [protected] |
For a prune cycle, this value is the average number of touches that an entry should have.
This value is used by the hybrid eviction policy.