00001 /* 00002 * CachingMap.hpp 00003 * 00004 * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved. 00005 * 00006 * Oracle is a registered trademarks of Oracle Corporation and/or its 00007 * affiliates. 00008 * 00009 * This software is the confidential and proprietary information of Oracle 00010 * Corporation. You shall not disclose such confidential and proprietary 00011 * information and shall use it only in accordance with the terms of the 00012 * license agreement you entered into with Oracle. 00013 * 00014 * This notice may not be removed or altered. 00015 */ 00016 #ifndef COH_CACHING_MAP_HPP 00017 #define COH_CACHING_MAP_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/internal/net/NamedCacheDeactivationListener.hpp" 00022 00023 #include "coherence/net/cache/CacheMap.hpp" 00024 #include "coherence/net/cache/SimpleCacheStatistics.hpp" 00025 #include "coherence/net/NamedCache.hpp" 00026 00027 #include "coherence/util/AbstractMapListener.hpp" 00028 #include "coherence/util/Collection.hpp" 00029 #include "coherence/util/ConcurrentMap.hpp" 00030 #include "coherence/util/Filter.hpp" 00031 #include "coherence/util/List.hpp" 00032 #include "coherence/util/Map.hpp" 00033 #include "coherence/util/MapListener.hpp" 00034 #include "coherence/util/MapListenerSupport.hpp" 00035 #include "coherence/util/MultiplexingMapListener.hpp" 00036 #include "coherence/util/Set.hpp" 00037 00038 #include "coherence/util/filter/CacheEventFilter.hpp" 00039 #include "coherence/util/filter/MapEventFilter.hpp" 00040 00041 COH_OPEN_NAMESPACE3(coherence,net,cache) 00042 00043 using coherence::internal::net::NamedCacheDeactivationListener; 00044 using coherence::net::NamedCache; 00045 using coherence::util::AbstractMapListener; 00046 using coherence::util::Collection; 00047 using coherence::util::ConcurrentMap; 00048 using coherence::util::Filter; 00049 using coherence::util::List; 00050 using coherence::util::Map; 00051 using coherence::util::MapListener; 00052 using coherence::util::MapListenerSupport; 00053 using coherence::util::MultiplexingMapListener; 00054 using coherence::util::Set; 00055 using coherence::util::filter::CacheEventFilter; 00056 using coherence::util::filter::MapEventFilter; 00057 00058 00059 /** 00060 * Map implementation that wraps two maps - a front map (assumed to be 00061 * "inexpensive" and probably "incomplete") and a back map (assumed to 00062 * be "complete" and "correct", but more "expensive") - using a 00063 * read-through/write-through approach. 00064 * 00065 * If the back map implements ObservableMap interface, the CachingMap provides 00066 * four different strategies of invalidating the front map entries that have 00067 * changed by other processes in the back map: 00068 * 00069 * listen_none strategy instructs the cache not to listen for invalidation 00070 * events at all. This is the best choice for raw performance and 00071 * scalability when business requirements permit the use of data which 00072 * might not be absolutely current. Freshness of data can be guaranteed 00073 * by use of a sufficiently brief eviction policy for the front map; 00074 * listen_present strategy instructs the CachingMap to listen to the 00075 * back map events related <b>only</b> to the items currently present in 00076 * the front map. This strategy works best when each instance of a front 00077 * map contains distinct subset of data relative to the other front map 00078 * instances (e.g. sticky data access patterns); 00079 * listen_all strategy instructs the CachingMap to listen to <b>all</b> 00080 * back map events. This strategy is optimal for read-heavy tiered access 00081 * patterns where there is significant overlap between the different 00082 * instances of front maps; 00083 * listen_auto strategy instructs the CachingMap implementation to switch 00084 * automatically between listen_present and listen_all strategies based 00085 * on the cache statistics. 00086 * listen_logical strategy instructs the CachingMap to listen to <b>all</b> 00087 * back map events that are <b>not synthetic</b>. A synthetic event could 00088 * be emitted as a result of eviction or expiration. With this 00089 * invalidation strategy, it is possible for the front map to contain 00090 * cache entries that have been synthetically removed from the back 00091 * (though any subsequent re-insertion will cause the corresponding 00092 * entries in the front map to be invalidated). 00093 * 00094 * The front map implementation is assumed to be thread safe; additionally 00095 * any modifications to the front map are allowed only after the corresponding 00096 * lock is acquired against the ControlMap. 00097 * 00098 * <b>Note:</b> NULL values are not cached in the front map and therefore this 00099 * implementation is not optimized for maps that allow NULL values to be 00100 * stored. 00101 * 00102 * @author tb 2008.06.12 00103 */ 00104 class COH_EXPORT CachingMap 00105 : public class_spec<CachingMap, 00106 extends<Object>, 00107 implements<Map> > 00108 { 00109 friend class factory<CachingMap>; 00110 00111 // ----- handle definitions (needed for nested classes) ----------------- 00112 00113 public: 00114 typedef this_spec::Handle Handle; 00115 typedef this_spec::View View; 00116 typedef this_spec::Holder Holder; 00117 00118 00119 // ----- enums ---------------------------------------------------------- 00120 00121 public: 00122 /** 00123 * Enum for invalidation strategies 00124 */ 00125 enum InvalidationStrategy 00126 { 00127 /** 00128 * No invalidation strategy. 00129 */ 00130 listen_none, 00131 00132 /** 00133 * Invalidation strategy that instructs the CachingMap to listen 00134 * to the back map events related <b>only</b> to the items 00135 * currently present in the front map; this strategy serves best 00136 * when the changes to the back map come mostly from the 00137 * CachingMap itself. 00138 */ 00139 listen_present, 00140 00141 /** 00142 * Invalidation strategy that instructs the CachingMap to listen 00143 * to <b>all</b> back map events; this strategy is preferred when 00144 * updates to the back map are frequent and with high probability 00145 * come from the outside of this CachingMap; for example multiple 00146 * CachingMap instances using the same back map with a large 00147 * degree of key set overlap between front maps. 00148 */ 00149 listen_all, 00150 00151 /** 00152 * Invalidation strategy that instructs the CachingMap 00153 * implementation to switch automatically between listen_present 00154 * and listen_all strategies based on the cache statistics. 00155 */ 00156 listen_auto, 00157 00158 /** 00159 * Invalidation strategy that instructs the CachingMap to listen 00160 * to <b>all</b> back map events that are <b>not synthetic</b>. A 00161 * synthetic event could be emitted as a result of eviction or 00162 * expiration. With this invalidation strategy, it is possible 00163 * for the front map to contain cache entries that have been 00164 * synthetically removed from the back (though any subsequent 00165 * re-insertion will cause the corresponding entries in the front 00166 * map to be invalidated). 00167 */ 00168 listen_logical 00169 }; 00170 00171 00172 // ----- constructors --------------------------------------------------- 00173 00174 protected: 00175 /** 00176 * Construct a CachingMap using two specified maps: 00177 * <i>FrontMap</i> (aka "cache", "near" or "shallow") and 00178 * <i>BackMap</i> (aka "actual", "real" or "deep"). 00179 * 00180 * If the BackMap implements the ObservableMap interface a listener 00181 * will be added to the BackMap to invalidate FrontMap items updated 00182 * [externally] in the back map using the listen_auto strategy. 00183 * 00184 * If no MapControl is specified then a new one is created. 00185 * 00186 * @param hMapFront front map 00187 * @param hMapBack back map 00188 * @param strategy specifies the strategy used for the front map 00189 * invalidation; valid values are LISTEN_* 00190 * constants 00191 * @param hMapControl the ConcurrentMap to keep track of front map 00192 * updates; may be NULL 00193 */ 00194 CachingMap(CacheMap::Handle hMapFront, CacheMap::Handle hMapBack, 00195 InvalidationStrategy strategy = listen_auto, 00196 ConcurrentMap::Handle hMapControl = NULL); 00197 00198 00199 // ----- life-cycle ----------------------------------------------------- 00200 00201 public: 00202 /** 00203 * Release the CachingMap. If the BackMap implements an ObservableMap 00204 * calling this method is necessary to remove the BackMap listener. 00205 * Any access to the CachingMap which has been released will cause 00206 * IllegalStateException. 00207 * 00208 * @throws IllegalStateException if accessing the CachingMap 00209 * which has been released 00210 */ 00211 virtual void release(); 00212 00213 00214 // ----- accessors ------------------------------------------------------ 00215 00216 public: 00217 /** 00218 * Obtain the front map reference. 00219 * 00220 * <b>Note:</b> direct modifications of the returned map may cause an 00221 * unpredictable behavior of the CachingMap. 00222 * 00223 * @return the front Map 00224 */ 00225 virtual CacheMap::Handle getFrontMap() const; 00226 00227 /** 00228 * Obtain the back map reference. 00229 * 00230 * <b>Note:</b> direct modifications of the returned map may cause an 00231 * unpredictable behavior of the CachingMap. 00232 * 00233 * @return the back Map 00234 */ 00235 virtual CacheMap::Handle getBackMap() const; 00236 00237 /** 00238 * Obtain the invalidation strategy used by this CachingMap. 00239 * 00240 * @return one of LISTEN_* values 00241 */ 00242 virtual InvalidationStrategy getInvalidationStrategy() const; 00243 00244 /** 00245 * Obtain the ConcurrentMap that should be used to synchronize 00246 * the front map modification access. 00247 * 00248 * @return a ConcurrentMap controlling the front map modifications 00249 */ 00250 virtual ConcurrentMap::Handle getControlMap() const; 00251 00252 /** 00253 * Obtain the CacheStatistics for this cache. 00254 * 00255 * @return a CacheStatistics object 00256 */ 00257 virtual CacheStatistics::Handle getCacheStatistics() const; 00258 00259 /** 00260 * Determine the rough number of front map invalidation hits since 00261 * the cache statistics were last reset. 00262 * 00263 * An invalidation hit is an externally induced map event for an entry 00264 * that exists in the front map. 00265 * 00266 * @return the number of cache invalidation hits 00267 */ 00268 virtual int64_t getInvalidationHits() const; 00269 00270 /** 00271 * Determine the rough number of front map invalidation misses since 00272 * the cache statistics were last reset. 00273 * 00274 * An invalidation miss is an externally induced map event for an 00275 * entry that does not exists in the front map. 00276 * 00277 * @return the number of cache invalidation misses 00278 */ 00279 virtual int64_t getInvalidationMisses() const; 00280 00281 /** 00282 * Determine the total number of registerListener(Object::View vKey) 00283 * operations since the cache statistics were last reset. 00284 * 00285 * @return the total number of listener registrations 00286 */ 00287 virtual int64_t getTotalRegisterListener() const; 00288 00289 protected: 00290 /** 00291 * Determine if changes to the back map affect the front map so that 00292 * data in the front map stays in sync. 00293 * 00294 * @return true if the front map has a means to stay in sync with the 00295 * back map so that it does not contain stale data 00296 */ 00297 virtual bool isCoherent() const; 00298 00299 00300 // ----- CachingMap interface ------------------------------------------- 00301 00302 protected: 00303 /** 00304 * Invalidate the key from the front. The caller must have the key 00305 * locked. 00306 * 00307 * @param vKey the key to invalidate 00308 */ 00309 virtual void invalidateFront(Object::View vKey) const; 00310 00311 /** 00312 * Helper method used by put() and putAll() to perform common 00313 * maintanence tasks after completing an operation against the back. 00314 * This includes removing the keys from the control map, and 00315 * evaluating if it is safe to update the front with the "new" value. 00316 * The implementation makes use of the following assumption: if 00317 * listEvents == IGNORE_LIST then oKey does not exist in the 00318 * front, and there is no key based listener for it. Any key passed 00319 * to this method must be locked in the control map by the caller. 00320 * 00321 * @param vKey the key 00322 * @param ohValue the new value 00323 * @param hlistEvents the event list associated with the key 00324 * @param cMillis the number of milliseconds until the cache entry 00325 * will expire 00326 */ 00327 virtual void finalizePut(Object::View vKey, Object::Holder ohValue, 00328 List::Handle hlistEvents, int64_t cMillis); 00329 00330 public: 00331 /** 00332 * Implementation of put method that optionally skips the return value 00333 * retrieval and allows to specify an expiry for the cache entry. 00334 * 00335 * @param vKey the key 00336 * @param ohValue the value 00337 * @param fReturn if true, the return value is required; otherwise 00338 * the return value will be ignored 00339 * @param cMillis the number of milliseconds until the cache entry 00340 * will expire 00341 * @return previous value (if required) 00342 * 00343 * @throws UnsupportedOperationException if the requested expiry is a 00344 * positive value and either the front map or the back map 00345 * implementations do not support the expiration functionality 00346 */ 00347 virtual Object::Holder put(Object::View vKey, Object::Holder ohValue, 00348 bool fReturn, int64_t cMillis); 00349 00350 /** 00351 * Get all the specified keys, if they are in the cache. For each key 00352 * that is in the cache, that key and its corresponding value will be 00353 * placed in the map that is returned by this method. The absence of 00354 * a key in the returned map indicates that it was not in the cache, 00355 * which may imply (for caches that can load behind the scenes) that 00356 * the requested data could not be loaded. 00357 * 00358 * <b>Note:</b> this implementation does not differentiate between 00359 * missing keys or NULL values stored in the back map; in both cases 00360 * the returned map will not contain the corresponding entry. 00361 * 00362 * @param vColKeys a collection of keys that may be in the named 00363 * cache 00364 * 00365 * @return a Map of keys to values for the specified keys passed in 00366 * <tt>col</tt> 00367 */ 00368 virtual Map::View getAll(Collection::View vColKeys) const; 00369 00370 00371 // ----- Map interface -------------------------------------------------- 00372 00373 public: 00374 /** 00375 * {@inheritDoc} 00376 */ 00377 virtual size32_t size() const; 00378 00379 /** 00380 * {@inheritDoc} 00381 */ 00382 virtual bool isEmpty() const; 00383 00384 /** 00385 * {@inheritDoc} 00386 */ 00387 virtual bool containsKey(Object::View vKey) const; 00388 00389 /** 00390 * {@inheritDoc} 00391 */ 00392 virtual bool containsValue(Object::View vValue) const; 00393 00394 /** 00395 * {@inheritDoc} 00396 */ 00397 virtual Object::Holder get(Object::View vKey) const; 00398 00399 /** 00400 * {@inheritDoc} 00401 */ 00402 virtual Object::Holder get(Object::View vKey); 00403 00404 /** 00405 * {@inheritDoc} 00406 */ 00407 virtual Object::Holder put(Object::View vKey, Object::Holder ohValue); 00408 00409 /** 00410 * {@inheritDoc} 00411 */ 00412 virtual Object::Holder remove(Object::View vKey); 00413 using Map::remove; 00414 00415 /** 00416 * {@inheritDoc} 00417 */ 00418 virtual void putAll(Map::View vMap); 00419 00420 /** 00421 * {@inheritDoc} 00422 */ 00423 virtual void clear(); 00424 00425 /** 00426 * {@inheritDoc} 00427 */ 00428 virtual Set::View keySet() const; 00429 00430 /** 00431 * {@inheritDoc} 00432 */ 00433 virtual Set::Handle keySet(); 00434 00435 /** 00436 * {@inheritDoc} 00437 */ 00438 virtual Collection::View values() const; 00439 00440 /** 00441 * {@inheritDoc} 00442 */ 00443 virtual Collection::Handle values(); 00444 00445 /** 00446 * {@inheritDoc} 00447 */ 00448 virtual Set::View entrySet() const; 00449 00450 /** 00451 * {@inheritDoc} 00452 */ 00453 virtual Set::Handle entrySet(); 00454 00455 00456 // ----- Object interface ----------------------------------------------- 00457 00458 public: 00459 /** 00460 * {@inheritDoc} 00461 */ 00462 virtual TypedHandle<const String> toString() const; 00463 00464 protected: 00465 /** 00466 * {@inheritDoc} 00467 */ 00468 virtual void onInit(); 00469 00470 00471 // ----- back map listener support -------------------------------------- 00472 00473 public: 00474 /** 00475 * Register the global back map listener. 00476 */ 00477 virtual void registerListener() const; 00478 00479 /** 00480 * Unregister the global back map listener. 00481 */ 00482 virtual void unregisterListener() const; 00483 00484 /** 00485 * Register the back map listener for the specified key. 00486 * 00487 * @param vKey the key 00488 */ 00489 virtual void registerListener(Object::View vKey) const; 00490 00491 /** 00492 * Register the back map listeners for the specified set of keys. 00493 * 00494 * @param hSetKeys the key set 00495 * 00496 * @since 12.2.1 00497 */ 00498 virtual void registerListeners(Set::Handle hSetKeys) const; 00499 00500 /** 00501 * Unregister the back map listener for the specified key. 00502 * 00503 * @param vKey the key 00504 */ 00505 virtual void unregisterListener(Object::View vKey) const; 00506 00507 /** 00508 * Unregister the back map listener for the specified keys. 00509 * 00510 * Note: all the keys in the passed-in set must be locked and will be 00511 * unlocked. 00512 * 00513 * @param hSetKeys Set of keys to unregister (and unlock) 00514 * 00515 * @since 12.2.1 00516 */ 00517 virtual void unregisterListeners(Set::Handle hSetKeys) const; 00518 00519 /** 00520 * Register the global front map listener. 00521 */ 00522 virtual void registerFrontListener() const; 00523 00524 /** 00525 * Unregister the global front map listener. 00526 */ 00527 virtual void unregisterFrontListener() const; 00528 00529 /** 00530 * Register back cache deactivation listener. 00531 */ 00532 virtual void registerDeactivationListener() const; 00533 00534 /** 00535 * Unregister back cache deactivation listener. 00536 */ 00537 virtual void unregisterDeactivationListener() const; 00538 00539 /** 00540 * Reset the front map 00541 */ 00542 virtual void resetFrontMap(); 00543 00544 /** 00545 * Ensure that a strategy has been choosen and that any appropriate 00546 * global listeners have been registered. 00547 * 00548 * @return the current strategy 00549 */ 00550 virtual InvalidationStrategy ensureInvalidationStrategy() const; 00551 00552 /** 00553 * Reset the "current invalidation strategy" flag. 00554 * 00555 * This method should be called <b>only</b> while the access to the 00556 * front map is fully synchronzied and the front map is empty to 00557 * prevent stalled data. 00558 */ 00559 virtual void resetInvalidationStrategy(); 00560 00561 // ----- inner class: PrimingListener ----------------------------------- 00562 00563 protected: 00564 /** 00565 * MapListener for back map responsible for keeping the front map 00566 * coherent with the back map. This listener is registered as a 00567 * synchronous listener for lite events (carrying only a key) and 00568 * generates a "priming" event when registered. 00569 * 00570 * @since 12.2.1 00571 */ 00572 class PrimingListener 00573 : public class_spec<PrimingListener, 00574 extends<MultiplexingMapListener>, 00575 implements<MapListenerSupport::PrimingListener> > 00576 { 00577 friend class factory<PrimingListener>; 00578 00579 // ----- constructors --------------------------------------- 00580 00581 protected: 00582 /** 00583 * Construct a PrimingListener 00584 * 00585 * @param hMap the map associated with this listener 00586 */ 00587 PrimingListener(CachingMap::Handle hMap); 00588 00589 // ----- MultiplexingMapListener interface ------------------ 00590 00591 /** 00592 * {@inheritDoc} 00593 */ 00594 virtual void onMapEvent(MapEvent::View vEvent); 00595 00596 // ---- data members ---------------------------------------- 00597 00598 protected: 00599 /** 00600 * The map associated with this listener. 00601 */ 00602 WeakHandle<CachingMap> m_whMap; 00603 }; 00604 00605 // ----- inner class: SimpleListener -------------------------------- 00606 00607 protected: 00608 /** 00609 * MapListener for back map responsible for keeping the front map 00610 * coherent with the back map. This listener is registered as a 00611 * synchronous listener for lite events (carrying only a key). 00612 */ 00613 class SimpleListener 00614 : public class_spec<SimpleListener, 00615 extends<MultiplexingMapListener>, 00616 implements<MapListenerSupport::SynchronousListener> > 00617 { 00618 friend class factory<SimpleListener>; 00619 00620 // ----- constructors --------------------------------------- 00621 00622 protected: 00623 /** 00624 * Construct a SimpleListener 00625 * 00626 * @param hMap the map associated with this listener 00627 */ 00628 SimpleListener(CachingMap::Handle hMap); 00629 00630 // ----- MultiplexingMapListener interface ------------------ 00631 00632 /** 00633 * {@inheritDoc} 00634 */ 00635 virtual void onMapEvent(MapEvent::View vEvent); 00636 00637 // ---- data members ---------------------------------------- 00638 00639 protected: 00640 /** 00641 * The map associated with this listener. 00642 */ 00643 WeakHandle<CachingMap> m_whMap; 00644 }; 00645 00646 // ----- inner class: DeactivationListener -------------------------- 00647 00648 protected: 00649 /** 00650 * DeactivationListener for the back NamedCache. 00651 * The primary goal of that listener is invalidation of the front map 00652 * when the back cache is destroyed or all storage nodes are stopped. 00653 */ 00654 class DeactivationListener 00655 : public class_spec<DeactivationListener, 00656 extends<AbstractMapListener>, 00657 implements<NamedCacheDeactivationListener> > 00658 { 00659 friend class factory<DeactivationListener>; 00660 00661 // ----- constructors --------------------------------------- 00662 00663 protected: 00664 /** 00665 * Construct a DeactivationListener 00666 * 00667 * @param hMap the map associated with this listener 00668 */ 00669 DeactivationListener(CachingMap::Handle hMap); 00670 00671 // ----- NamedCacheDeactivationListener interface ------------------ 00672 00673 /** 00674 * {@inheritDoc} 00675 */ 00676 virtual void entryDeleted(MapEvent::View vEvent); 00677 00678 /** 00679 * {@inheritDoc} 00680 */ 00681 virtual void entryUpdated(MapEvent::View vEvent); 00682 00683 // ---- data members ---------------------------------------- 00684 00685 protected: 00686 /** 00687 * The map associated with this listener. 00688 */ 00689 WeakHandle<CachingMap> m_whMap; 00690 }; 00691 00692 // ----- inner class: FrontMapListener ---------------------------------- 00693 00694 protected: 00695 /** 00696 * MapListener for back map responsible for keeping the front map 00697 * coherent with the back map. This listener is registered as a 00698 * synchronous listener for lite events (carrying only a key). 00699 */ 00700 class FrontMapListener 00701 : public class_spec<FrontMapListener, 00702 extends<AbstractMapListener>, 00703 implements<MapListenerSupport::SynchronousListener> > 00704 { 00705 friend class factory<FrontMapListener>; 00706 00707 // ----- constructors --------------------------------------- 00708 00709 protected: 00710 /** 00711 * Construct a FrontMapListener 00712 * 00713 * @param hMap the map associated with this listener 00714 */ 00715 FrontMapListener(CachingMap::Handle hMap); 00716 00717 // ----- MapListener interface ------------------------------ 00718 00719 public: 00720 /** 00721 * {@inheritDoc} 00722 */ 00723 virtual void entryDeleted(MapEvent::View vEvent); 00724 00725 // ---- helper registration methods ------------------------- 00726 00727 public: 00728 /** 00729 * Register this listener with the "front" map. 00730 */ 00731 virtual void registerWithMap(); 00732 00733 /** 00734 * Unregister this listener with the "front" map. 00735 */ 00736 virtual void unregisterFromMap(); 00737 00738 // ---- data members ---------------------------------------- 00739 00740 protected: 00741 /** 00742 * The filter associated with this listener. 00743 */ 00744 FinalView<Filter> f_vFilter; 00745 00746 /** 00747 * The map associated with this listener. 00748 */ 00749 WeakHandle<CachingMap> m_whMap; 00750 }; 00751 00752 00753 // ----- listener support ----------------------------------------------- 00754 00755 protected: 00756 /** 00757 * Factory pattern: instantiate back map listener. 00758 * 00759 * @param strategy the strategy to instantiate a back map listener for 00760 * 00761 * @return an instance of back map listener responsible for keeping 00762 * the front map coherent with the back map 00763 */ 00764 virtual MapListener::Handle instantiateBackMapListener(InvalidationStrategy strategy); 00765 00766 /** 00767 * Factory pattern: instantiate front map listener. 00768 * 00769 * @return an instance of front map listener 00770 */ 00771 virtual FrontMapListener::Handle instantiateFrontMapListener(); 00772 00773 /** 00774 * Validate the front map entry for the specified back map event. 00775 * 00776 * @param vEvent the MapEvent from the back map 00777 */ 00778 virtual void validate(MapEvent::View vEvent); 00779 00780 /** 00781 * Set up a thread local Set to hold all the keys that might be evicted 00782 * from the front cache. 00783 * 00784 * @return a Set to hold all the keys in the ThreadLocal object or null 00785 * if the bulk unregistering is not needed 00786 * 00787 * @since 12.2.1 00788 */ 00789 virtual Set::Handle setKeyHolder() const; 00790 00791 /** 00792 * Remove the key holder from the ThreadLocal object. 00793 * 00794 * @since 12.2.1 00795 */ 00796 virtual void removeKeyHolder() const; 00797 00798 /** 00799 * Check if the specified event is a "priming" one. 00800 * 00801 * @since 12.2.1 00802 */ 00803 static bool isPriming(MapEvent::View vEvent); 00804 00805 // ----- constants and data fields ------------------------------------- 00806 00807 protected : 00808 /** 00809 * The "back" map, considered to be "complete" yet "expensive" to 00810 * access. 00811 */ 00812 mutable FinalHandle<CacheMap> f_hMapBack; 00813 00814 /** 00815 * The "front" map, considered to be "incomplete" yet "inexpensive" to 00816 * access. 00817 */ 00818 mutable FinalHandle<CacheMap> f_hMapFront; 00819 00820 /** 00821 * The invalidation strategy that this map is to use. 00822 */ 00823 mutable InvalidationStrategy m_strategyTarget; 00824 00825 /** 00826 * The current invalidation strategy, which at times could be different 00827 * from the target strategy. 00828 */ 00829 mutable InvalidationStrategy m_strategyCurrent; 00830 00831 /** 00832 * An optional listener for the "back" map. 00833 */ 00834 mutable MemberHandle<MapListener> m_hListener; 00835 00836 /** 00837 * An optional Simplelistener for the "back" map. 00838 * @see note in CachingMap::onInit() 00839 * 00840 * @since 12.2.1 00841 */ 00842 mutable MemberHandle<MapListener> m_hSimpleListener; 00843 00844 /** 00845 * An optional DeactivationListener for the "back" map. 00846 * @see note in CachingMap::onInit() 00847 * 00848 * @since 12.1.3 00849 */ 00850 mutable MemberHandle<DeactivationListener> m_hListenerDeactivation; 00851 00852 /** 00853 * An optional listener for the "front" map. 00854 */ 00855 mutable FinalHandle<FrontMapListener> f_hListenerFront; 00856 00857 /** 00858 * A filter that selects events for the back-map listener. 00859 */ 00860 mutable MemberHandle<Filter> m_hFilterListener; 00861 00862 /** 00863 * The ConcurrentMap to keep track of front map updates. 00864 * Values are list of events received by the listener while the 00865 * corresponding key was locked. Use of LOCK_ALL is restricited to 00866 * non-blocking operations to prevent deadlock with the service thread. 00867 */ 00868 mutable FinalHandle<ConcurrentMap> f_hMapControl; 00869 00870 /** 00871 * The CacheStatistics object maintained by this cache. 00872 */ 00873 mutable FinalHandle<SimpleCacheStatistics> f_hStats; 00874 00875 /** 00876 * The rough (ie unsynchronized) number of times the front map entries 00877 * that were present in the front map were invalidated by the listener. 00878 */ 00879 mutable /*volatile stat*/ int64_t m_cInvalidationHits; 00880 00881 /** 00882 * The rough (ie unsynchronized) number of times the front map entries 00883 * that were absent in the front map received invalidation event. 00884 */ 00885 mutable /*volatile stat*/ int64_t m_cInvalidationMisses; 00886 00887 /** 00888 * The total number of registerListener(oKey) operations. 00889 */ 00890 mutable /*volatile stat*/ int64_t m_cRegisterListener; 00891 00892 /** 00893 * True if the cache has been released. 00894 */ 00895 bool m_fReleased; 00896 00897 /** 00898 * The ThreadLocal to hold all the keys that are evicted while the front cache 00899 * is updated during get or getAll operation. 00900 * 00901 * @since 12.2.1 00902 */ 00903 mutable FinalHandle<ThreadLocalReference> f_htloKeys; 00904 00905 // ----- constants ------------------------------------------------------ 00906 00907 protected : 00908 /** 00909 * A unique Object that serves as a control key for global operations 00910 * such as clear and release and synchronization point for the current 00911 * strategy change. 00912 */ 00913 FinalView<Object> f_vKeyGlobal; 00914 }; 00915 00916 COH_CLOSE_NAMESPACE3 00917 00918 #endif // COH_CACHING_MAP_HPP