#include <coherence/net/cache/CachingMap.hpp>
Inherited by NearCache.
If the back map implements ObservableMap interface, the CachingMap provides four different strategies of invalidating the front map entries that have changed by other processes in the back map:
listen_none 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 map; listen_present strategy instructs the CachingMap to listen to the back map events related only to the items currently present in the front map. This strategy works best when each instance of a front map contains distinct subset of data relative to the other front map instances (e.g. sticky data access patterns); listen_all strategy instructs the CachingMap to listen to all back map events. This strategy is optimal for read-heavy tiered access patterns where there is significant overlap between the different instances of front maps; listen_auto strategy instructs the CachingMap implementation to switch automatically between listen_present and listen_all strategies based on the cache statistics. listen_logical strategy instructs the CachingMap 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 strategy, 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 map implementation is assumed to be thread safe; additionally any modifications to the front map are allowed only after the corresponding lock is acquired against the ControlMap.
Note: NULL values are not cached in the front map and therefore this implementation is not optimized for maps that allow NULL values to be stored.
Public Types | ||||||||||
| enum | InvalidationStrategy { listen_none, listen_present, listen_all, listen_auto, listen_logical } | |||||||||
| Enum for invalidation strategies. More... | ||||||||||
| typedef spec::Handle | Handle | |||||||||
| CachingMap Handle definition. | ||||||||||
| typedef spec::View | View | |||||||||
| CachingMap View definition. | ||||||||||
| typedef spec::Holder | Holder | |||||||||
| CachingMap Holder definition. | ||||||||||
| typedef this_spec::Handle | Handle | |||||||||
| Object Handle definition. | ||||||||||
| typedef this_spec::View | View | |||||||||
| Object View definition. | ||||||||||
| typedef this_spec::Holder | Holder | |||||||||
| Object Holder definition. | ||||||||||
Public Member Functions | ||||||||||
| virtual void | release () | |||||||||
| Release the CachingMap. | ||||||||||
| virtual CacheMap::Handle | getFrontMap () const | |||||||||
| Obtain the front map reference. | ||||||||||
| virtual CacheMap::Handle | getBackMap () const | |||||||||
| Obtain the back map reference. | ||||||||||
| virtual InvalidationStrategy | getInvalidationStrategy () const | |||||||||
| Obtain the invalidation strategy used by this CachingMap. | ||||||||||
| virtual ConcurrentMap::Handle | getControlMap () const | |||||||||
| Obtain the ConcurrentMap that should be used to synchronize the front map modification access. | ||||||||||
| virtual CacheStatistics::Handle | getCacheStatistics () const | |||||||||
| Obtain the CacheStatistics for this cache. | ||||||||||
| virtual int64_t | getInvalidationHits () const | |||||||||
| Determine the rough number of front map invalidation hits since the cache statistics were last reset. | ||||||||||
| virtual int64_t | getInvalidationMisses () const | |||||||||
| Determine the rough number of front map invalidation misses since the cache statistics were last reset. | ||||||||||
| virtual int64_t | getTotalRegisterListener () const | |||||||||
| Determine the total number of registerListener(Object::View vKey) operations since the cache statistics were last reset. | ||||||||||
| virtual Object::Holder | put (Object::View vKey, Object::Holder ohValue, bool fReturn, int64_t cMillis) | |||||||||
| Implementation of put method that optionally skips the return value retrieval and allows to specify an expiry for the cache entry. | ||||||||||
| virtual Map::View | getAll (Collection::View vColKeys) const | |||||||||
| Get all the specified keys, if they are in the cache. | ||||||||||
| virtual size32_t | size () const | |||||||||
| Return the number of key-value mappings in this map.
| ||||||||||
| virtual bool | isEmpty () const | |||||||||
Return true if this map contains no key-value mappings.
| ||||||||||
| virtual bool | containsKey (Object::View vKey) const | |||||||||
Return true if this map contains a mapping for the specified key.
| ||||||||||
| virtual bool | containsValue (Object::View vValue) const | |||||||||
Return true if this map maps one or more keys to the specified value.
This operation will probably require time linear in the map size for most implementations of the
| ||||||||||
| virtual Object::Holder | get (Object::View vKey) const | |||||||||
| Return the value to which this map maps the specified key.
Return
| ||||||||||
| virtual Object::Holder | get (Object::View vKey) | |||||||||
| Return the value to which this map maps the specified key.
Return
| ||||||||||
| virtual Object::Holder | put (Object::View vKey, Object::Holder ohValue) | |||||||||
| Associate the specified value with the specified key in this map. If the map previously contained a mapping for this key, the old value is replaced by the specified value.
| ||||||||||
| virtual Object::Holder | remove (Object::View vKey) | |||||||||
| Remove the mapping for this key from this map if it is present.
Return the value to which the map previously associated the key, or
| ||||||||||
| virtual void | putAll (Map::View vMap) | |||||||||
| virtual void | clear () | |||||||||
| Remove all mappings from this map.
| ||||||||||
| virtual Set::View | keySet () const | |||||||||
| Return a set of the keys contained in this map. The set is backed by the map, so changes to the map are reflected in the set. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined.
| ||||||||||
| virtual Set::Handle | keySet () | |||||||||
| Return a set of the keys contained in this map. The set is backed by the map, so changes to one are reflected in the other. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined.
| ||||||||||
| virtual Collection::View | values () const | |||||||||
| Return a collection of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the set. If the map is modified while an iteration over the collection is in progress, the results of the iteration are undefined.
| ||||||||||
|
virtual Collection::Handle | values () | |||||||||
| Return a collection of the values contained in this map. The collection is backed by the map, so changes to one are reflected in the other. If the map is modified while an iteration over the collection is in progress, the results of the iteration are undefined.
| ||||||||||
| virtual Set::View | entrySet () const | |||||||||
| Return a set of the mappings contained in this map. Each element in the returned set is a Map::Entry::View. The set is backed by the map, so changes to the map are reflected in the set. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined.
| ||||||||||
| virtual Set::Handle | entrySet () | |||||||||
| Return a set of the mappings contained in this map. Each element in the returned set is a Map::Entry::Handle. The set is backed by the map, so changes to one are reflected in the other. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined.
| ||||||||||
| virtual void | toStream (std::ostream &out) const | |||||||||
| Output a human-readable description of this Object to the given stream. coherence::lang::operator<<(std::ostream, Object::View) is defined and will call into the toStream method, to output Objects. If a managed String object is desired, the COH_TO_STRING macro can be used to build up a String from streamable contents.
Object::View vKey = ... Object::View vValue = ... std::cout << vKey << " = " << vValue << std::endl; String::Handle hs = COH_TO_STRING(vKey << " = " << vValue);
| ||||||||||
| virtual void | registerListener () const | |||||||||
| Register the global back map listener. | ||||||||||
| virtual void | unregisterListener () const | |||||||||
| Unregister the global back map listener. | ||||||||||
| virtual void | registerListener (Object::View vKey) const | |||||||||
| Register the back map listener for the specified key. | ||||||||||
| virtual void | unregisterListener (Object::View vKey) const | |||||||||
| Unregister the back map listener for the specified key. | ||||||||||
| virtual void | registerFrontListener () const | |||||||||
| Register the global front map listener. | ||||||||||
| virtual void | unregisterFrontListener () const | |||||||||
| Unregister the global front map listener. | ||||||||||
| virtual InvalidationStrategy | ensureInvalidationStrategy () const | |||||||||
| Ensure that a strategy has been choosen and that any appropriate global listeners have been registered. | ||||||||||
| virtual void | resetInvalidationStrategy () | |||||||||
| Reset the "current invalidation strategy" flag. | ||||||||||
Protected Member Functions | ||||||||||
| CachingMap (CacheMap::Handle hMapFront, CacheMap::Handle hMapBack, InvalidationStrategy strategy=listen_auto, ConcurrentMap::Handle hMapControl=NULL) | ||||||||||
| Construct a CachingMap using two specified maps: FrontMap (aka "cache", "near" or "shallow") and BackMap (aka "actual", "real" or "deep"). | ||||||||||
| virtual bool | isCoherent () const | |||||||||
| Determine if changes to the back map affect the front map so that data in the front map stays in sync. | ||||||||||
| virtual void | invalidateFront (Object::View vKey) const | |||||||||
| Invalidate the key from the front. | ||||||||||
| virtual void | finalizePut (Object::View vKey, Object::Holder ohValue, List::Handle hlistEvents, int64_t cMillis) | |||||||||
| Helper method used by put() and putAll() to perform common maintanence tasks after completing an operation against the back. | ||||||||||
| virtual void | onInit () | |||||||||
| Event called once the Object has finished being constructed. Specifically when the first attachment is made. This provides a safe point at which Handles/Views to "this" can be created. It is not safe to create Handles/Views to an Object from within its constructor, thus any operations which rely upon this should be deferred until the onInit event is triggered. As with all event methods any derived implementation should include a call to the super class's implementation. Specifically delegation to Object::onInit() must eventually occur or an IllegalStateException will result.
The default implementation calls the onInit() method of each of the Object's SmartMembers. | ||||||||||
| virtual MapListener::Handle | instantiateBackMapListener () | |||||||||
| Factory pattern: instantiate back map listener. | ||||||||||
| virtual FrontMapListener::Handle | instantiateFrontMapListener () | |||||||||
| Factory pattern: instantiate front map listener. | ||||||||||
| virtual void | validate (MapEvent::View vEvent) | |||||||||
| Validate the front map entry for the specified back map event. | ||||||||||
Protected Attributes | ||||||||||
| FinalHandle< CacheMap > | f_hMapBack | |||||||||
| The "back" map, considered to be "complete" yet "expensive" to access. | ||||||||||
| FinalHandle< CacheMap > | f_hMapFront | |||||||||
| The "front" map, considered to be "incomplete" yet "inexpensive" to access. | ||||||||||
| InvalidationStrategy | m_strategyTarget | |||||||||
| The invalidation strategy that this map is to use. | ||||||||||
| InvalidationStrategy | m_strategyCurrent | |||||||||
| The current invalidation strategy, which at times could be different from the target strategy. | ||||||||||
|
MemberHandle < MapListener > | m_hListener | |||||||||
| An optional listener for the "back" map. | ||||||||||
|
FinalHandle < FrontMapListener > | f_hListenerFront | |||||||||
| An optional listener for the "front" map. | ||||||||||
| MemberHandle< Filter > | m_hFilterListener | |||||||||
| A filter that selects events for the back-map listener. | ||||||||||
| FinalHandle < ConcurrentMap > | f_hMapControl | |||||||||
| The ConcurrentMap to keep track of front map updates. | ||||||||||
|
FinalHandle < SimpleCacheStatistics > | f_hStats | |||||||||
| The CacheStatistics object maintained by this cache. | ||||||||||
| int64_t | m_cInvalidationHits | |||||||||
| The rough (ie unsynchronized) number of times the front map entries that were present in the front map were invalidated by the listener. | ||||||||||
| int64_t | m_cInvalidationMisses | |||||||||
| The rough (ie unsynchronized) number of times the front map entries that were absent in the front map received invalidation event. | ||||||||||
| int64_t | m_cRegisterListener | |||||||||
| The total number of registerListener(oKey) operations. | ||||||||||
| bool | m_fReleased | |||||||||
| True if the cache has been released. | ||||||||||
| FinalView< Object > | f_vKeyGlobal | |||||||||
| A unique Object that serves as a control key for global operations such as clear and release and synchronization point for the current strategy change. | ||||||||||
Classes | ||||||||||
| class | BackMapListener | |||||||||
| MapListener for back map responsible for keeping the front map coherent with the back map. More... | ||||||||||
| class | FrontMapListener | |||||||||
| MapListener for back map responsible for keeping the front map coherent with the back map. More... | ||||||||||
| enum InvalidationStrategy |
Enum for invalidation strategies.
| listen_none | No invalidation strategy. |
| listen_present | Invalidation strategy that instructs the CachingMap to listen to the back map events related only to the items currently present in the front map; this strategy serves best when the changes to the back map come mostly from the CachingMap itself. |
| listen_all | Invalidation strategy that instructs the CachingMap to listen to all back map events; this strategy is preferred when updates to the back map are frequent and with high probability come from the outside of this CachingMap; for example multiple CachingMap instances using the same back map with a large degree of key set overlap between front maps. |
| listen_auto | Invalidation strategy that instructs the CachingMap implementation to switch automatically between listen_present and listen_all strategies based on the cache statistics. |
| listen_logical |
Invalidation strategy that instructs the CachingMap 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 strategy, 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). |
| CachingMap | ( | CacheMap::Handle | hMapFront, | |
| CacheMap::Handle | hMapBack, | |||
| InvalidationStrategy | strategy = listen_auto, |
|||
| ConcurrentMap::Handle | hMapControl = NULL | |||
| ) | [protected] |
Construct a CachingMap using two specified maps: FrontMap (aka "cache", "near" or "shallow") and BackMap (aka "actual", "real" or "deep").
If the BackMap implements the ObservableMap interface a listener will be added to the BackMap to invalidate FrontMap items updated [externally] in the back map using the listen_auto strategy.
If no MapControl is specified then a new one is created.
| hMapFront | front map | |
| hMapBack | back map | |
| strategy | specifies the strategy used for the front map invalidation; valid values are LISTEN_* constants | |
| hMapControl | the ConcurrentMap to keep track of front map updates; may be NULL |
| virtual void release | ( | ) | [virtual] |
Release the CachingMap.
If the BackMap implements an ObservableMap calling this method is necessary to remove the BackMap listener. Any access to the CachingMap which has been released will cause IllegalStateException.
| IllegalStateException | if accessing the CachingMap which has been released |
Reimplemented in NearCache.
| virtual CacheMap::Handle getFrontMap | ( | ) | const [virtual] |
Obtain the front map reference.
Note: direct modifications of the returned map may cause an unpredictable behavior of the CachingMap.
| virtual CacheMap::Handle getBackMap | ( | ) | const [virtual] |
Obtain the back map reference.
Note: direct modifications of the returned map may cause an unpredictable behavior of the CachingMap.
| virtual InvalidationStrategy getInvalidationStrategy | ( | ) | const [virtual] |
| virtual ConcurrentMap::Handle getControlMap | ( | ) | const [virtual] |
Obtain the ConcurrentMap that should be used to synchronize the front map modification access.
| virtual CacheStatistics::Handle getCacheStatistics | ( | ) | const [virtual] |
| virtual int64_t getInvalidationHits | ( | ) | const [virtual] |
| virtual int64_t getInvalidationMisses | ( | ) | const [virtual] |
| virtual int64_t getTotalRegisterListener | ( | ) | const [virtual] |
Determine the total number of registerListener(Object::View vKey) operations since the cache statistics were last reset.
| virtual bool isCoherent | ( | ) | const [protected, virtual] |
Determine if changes to the back map affect the front map so that data in the front map stays in sync.
| virtual void invalidateFront | ( | Object::View | vKey | ) | const [protected, virtual] |
Invalidate the key from the front.
The caller must have the key locked.
| vKey | the key to invalidate |
| virtual void finalizePut | ( | Object::View | vKey, | |
| Object::Holder | ohValue, | |||
| List::Handle | hlistEvents, | |||
| int64_t | cMillis | |||
| ) | [protected, virtual] |
Helper method used by put() and putAll() to perform common maintanence tasks after completing an operation against the back.
This includes removing the keys from the control map, and evaluating if it is safe to update the front with the "new" value. The implementation makes use of the following assumption: if listEvents == IGNORE_LIST then oKey does not exist in the front, and there is no key based listener for it. Any key passed to this method must be locked in the control map by the caller.
| vKey | the key | |
| ohValue | the new value | |
| hlistEvents | the event list associated with the key | |
| cMillis | the number of milliseconds until the cache entry will expire |
| virtual Object::Holder put | ( | Object::View | vKey, | |
| Object::Holder | ohValue, | |||
| bool | fReturn, | |||
| int64_t | cMillis | |||
| ) | [virtual] |
Implementation of put method that optionally skips the return value retrieval and allows to specify an expiry for the cache entry.
| vKey | the key | |
| ohValue | the value | |
| fReturn | if true, the return value is required; otherwise the return value will be ignored | |
| cMillis | the number of milliseconds until the cache entry will expire |
| UnsupportedOperationException | if the requested expiry is a positive value and either the front map or the back map implementations do not support the expiration functionality |
| virtual Map::View getAll | ( | Collection::View | vColKeys | ) | const [virtual] |
Get all the specified keys, if they are in the cache.
For each key that is in the cache, that key and its corresponding value will be placed in the map that is returned by this method. The absence of a key in the returned map 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 map; in both cases the returned map will not contain the corresponding entry.
| vColKeys | a collection of keys that may be in the named cache |
col Reimplemented in NearCache.
| virtual void registerListener | ( | Object::View | vKey | ) | const [virtual] |
Register the back map listener for the specified key.
| vKey | the key |
| virtual void unregisterListener | ( | Object::View | vKey | ) | const [virtual] |
Unregister the back map listener for the specified key.
| vKey | the key |
| virtual InvalidationStrategy ensureInvalidationStrategy | ( | ) | const [virtual] |
Ensure that a strategy has been choosen and that any appropriate global listeners have been registered.
| virtual void resetInvalidationStrategy | ( | ) | [virtual] |
Reset the "current invalidation strategy" flag.
This method should be called only while the access to the front map is fully synchronzied and the front map is empty to prevent stalled data.
| virtual MapListener::Handle instantiateBackMapListener | ( | ) | [protected, virtual] |
Factory pattern: instantiate back map listener.
| virtual FrontMapListener::Handle instantiateFrontMapListener | ( | ) | [protected, virtual] |
Factory pattern: instantiate front map listener.
| virtual void validate | ( | MapEvent::View | vEvent | ) | [protected, virtual] |
Validate the front map entry for the specified back map event.
| vEvent | the MapEvent from the back map |
FinalHandle<ConcurrentMap> f_hMapControl [mutable, protected] |
The ConcurrentMap to keep track of front map updates.
Values are list of events received by the listener while the corresponding key was locked. Use of LOCK_ALL is restricited to non-blocking operations to prevent deadlock with the service thread.