00001 /* 00002 * OldCache.hpp 00003 * 00004 * Copyright (c) 2000, 2020, 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_OLD_CACHE_HPP 00017 #define COH_OLD_CACHE_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/net/cache/CacheMap.hpp" 00022 #include "coherence/net/cache/EvictionPolicy.hpp" 00023 #include "coherence/net/cache/SimpleCacheStatistics.hpp" 00024 #include "coherence/net/cache/UnitCalculator.hpp" 00025 00026 #include "coherence/util/Collection.hpp" 00027 #include "coherence/util/Comparator.hpp" 00028 #include "coherence/util/Filter.hpp" 00029 #include "coherence/util/InvocableMap.hpp" 00030 #include "coherence/util/Iterator.hpp" 00031 #include "coherence/util/Map.hpp" 00032 #include "coherence/util/MapKeySet.hpp" 00033 #include "coherence/util/MapListener.hpp" 00034 #include "coherence/util/MapListenerSupport.hpp" 00035 #include "coherence/util/MapValuesCollection.hpp" 00036 #include "coherence/util/Muterator.hpp" 00037 #include "coherence/util/ObservableMap.hpp" 00038 #include "coherence/util/SafeHashMap.hpp" 00039 #include "coherence/util/Set.hpp" 00040 #include "coherence/util/ValueExtractor.hpp" 00041 00042 00043 00044 COH_OPEN_NAMESPACE3(coherence,net,cache) 00045 00046 using coherence::util::Collection; 00047 using coherence::util::Comparator; 00048 using coherence::util::Filter; 00049 using coherence::util::InvocableMap; 00050 using coherence::util::Iterator; 00051 using coherence::util::Map; 00052 using coherence::util::MapKeySet; 00053 using coherence::util::MapListener; 00054 using coherence::util::MapListenerSupport; 00055 using coherence::util::MapValuesCollection; 00056 using coherence::util::Muterator; 00057 using coherence::util::ObservableMap; 00058 using coherence::util::SafeHashMap; 00059 using coherence::util::Set; 00060 using coherence::util::ValueExtractor; 00061 00062 00063 /** 00064 * A generic cache manager. 00065 * 00066 * The implementation is thread safe and uses a combination of 00067 * Most Recently Used (MRU) and Most Frequently Used (MFU) caching 00068 * strategies. 00069 * 00070 * The cache is size-limited, which means that once it reaches its maximum 00071 * size ("high-water mark") it prunes itself (to its "low-water mark"). The 00072 * cache high- and low-water-marks are measured in terms of "units", and each 00073 * cached item by default uses one unit. All of the cache constructors, except 00074 * for the default constructor, require the maximum number of units to be 00075 * passed in. To change the number of units that each cache entry uses, either 00076 * set the Units property of the cache entry, or extend the Cache 00077 * implementation so that the inner Entry class calculates its own unit size. 00078 * To determine the current, high-water and low-water sizes of the cache, use 00079 * the cache object's Units, HighUnits and LowUnits properties. The HighUnits 00080 * and LowUnits properties can be changed, even after the cache is in use. 00081 * To specify the LowUnits value as a percentage when constructing the cache, 00082 * use the extended constructor taking the percentage-prune-level. 00083 * 00084 * Each cached entry expires after one hour by default. To alter this 00085 * behavior, use a constructor that takes the expiry-millis; for example, an 00086 * expiry-millis value of 10000 will expire entries after 10 seconds. The 00087 * ExpiryDelay property can also be set once the cache is in use, but it 00088 * will not affect the expiry of previously cached items. 00089 * 00090 * The cache can optionally be flushed on a periodic basis by setting 00091 * the FlushDelay property or scheduling a specific flush time by setting 00092 * the FlushTime property. 00093 * 00094 * Cache hit statistics can be obtained from the CacheHits, CacheMisses, 00095 * HitProbability, KeyHitProbability and CompositeHitProbability read-only 00096 * properties. The statistics can be reset by invoking resetHitStatistics. 00097 * The statistics are automatically reset when the cache is cleared (the clear 00098 * method). 00099 * 00100 * The OldCache implements the ObservableMap interface, meaning it provides 00101 * event notifications to any interested listener for each insert, update and 00102 * delete, including those that occur when the cache is pruned or entries 00103 * are automatically expired. 00104 * 00105 * This implementation is designed to support extension through inheritence. 00106 * When overriding the inner Entry class, the OldCache.instantiateEntry factory 00107 * method must be overridden to instantiate the correct Entry sub-class. To 00108 * override the one-unit-per-entry default behavior, extend the inner Entry 00109 * class and override the calculateUnits method. 00110 * 00111 * The C++ version of OldCache requires a call release(), in order for it to 00112 * be collected. Not including a call to release will result in the OldCache 00113 * being leaked. 00114 * 00115 * @author nsa 2008.06.23 00116 */ 00117 class COH_EXPORT OldCache 00118 : public class_spec<OldCache, 00119 extends<SafeHashMap>, 00120 implements<ObservableMap, CacheMap> > 00121 { 00122 friend class factory<OldCache>; 00123 00124 // ----- handle definitions (needed for nested classes) ----------------- 00125 00126 public: 00127 typedef this_spec::Handle Handle; 00128 typedef this_spec::View View; 00129 typedef this_spec::Holder Holder; 00130 00131 00132 // ----- constants ------------------------------------------------------ 00133 public: 00134 /** 00135 * By default, the cache size (in units). 00136 */ 00137 static const size32_t default_units = 1000; 00138 00139 /** 00140 * By default, the cache entries expire after one hour. 00141 */ 00142 static const int32_t default_expire = 3600000; 00143 00144 /** 00145 * By default, expired cache entries are flushed on a minute interval. 00146 */ 00147 static const int32_t default_flush = 60000; 00148 00149 /** 00150 * Unit calculator configuration enum 00151 */ 00152 typedef enum 00153 { 00154 /** 00155 * Specifies the default unit calculator that weighs all entries 00156 * equally as 1. 00157 */ 00158 unit_calculator_fixed = 0, 00159 /** 00160 * Specifies an external (custom) unit calculator implementation. 00161 */ 00162 unit_calculator_external = 2 00163 } UnitCalculatorType; 00164 00165 /** 00166 * By default, when the cache prunes, it reduces its entries by 25%, 00167 * meaning it retains 75% (.75) of its entries. 00168 */ 00169 static float64_t getDefaultPrune(); 00170 00171 00172 // ----- constructors --------------------------------------------------- 00173 00174 protected: 00175 /** 00176 * Construct an instanceo of OldCache 00177 * 00178 * @param vsName the Name of the cache to construct 00179 * @param cUnits the number of units that the cache manager 00180 * will cache before pruning the cache 00181 * @param cExpiryMillis the number of milliseconds that each cache 00182 * entry lives before being automatically 00183 * expired 00184 * @param dflPruneLevel the percentage of the total number of units 00185 * that will remain after the cache manager 00186 * prunes the cache (i.e. this is the 00187 * "low water mark" value); this value is in 00188 * the range 0.0 to 1.0 00189 * @param cInitialBuckets the initial number of hash buckets, 00190 * 0 < n 00191 * @param flLoadFactor the acceptable load factor before resizing 00192 * occurs, 0 < n, such that a load factor 00193 * of 1.0 causes resizing when the number of 00194 * entries exceeds the number of buckets 00195 * @param flGrowthRate the rate of bucket growth when a resize 00196 * occurs, 0 < n, such that a growth rate 00197 * of 1.0 will double the number of buckets: 00198 * bucketcount = bucketcount * (1 + growthrate) 00199 */ 00200 OldCache(size32_t cUnits = default_units, 00201 int32_t cExpiryMillis = default_expire, 00202 float64_t dflPruneLevel = 0.75F, 00203 size32_t cInitialBuckets = 17, 00204 float32_t flLoadFactor = 1.0F, 00205 float32_t flGrowthRate = 3.0F); 00206 00207 00208 // ----- forward declarations ------------------------------------------- 00209 00210 protected: 00211 class KeySet; 00212 class ValuesCollection; 00213 00214 00215 // ----- inner class: Entry --------------------------------------------- 00216 00217 public: 00218 /** 00219 * Entry for the local cache extends SafeHashMap::Entry adding 00220 * entry statistics used for the various eviction policies 00221 */ 00222 class COH_EXPORT Entry 00223 : public cloneable_spec<Entry, 00224 extends<SafeHashMap::Entry> > 00225 { 00226 friend class factory<Entry>; 00227 00228 // ----- constructor ---------------------------------------- 00229 00230 protected: 00231 /** 00232 * Create a new OldCache::Entry 00233 * 00234 * @param vKey the associated key 00235 * @param ohValue the associated value 00236 * @param nHash the associated hash code 00237 * @param hCache reference to the cache containing this 00238 * entry 00239 */ 00240 Entry(Object::View vKey, Object::Holder ohValue, 00241 size32_t nHash, OldCache::Handle hCache); 00242 00243 /** 00244 * Copy constructor 00245 */ 00246 Entry(const Entry& that); 00247 00248 /** 00249 * Copy an Entry. 00250 * 00251 * @param vThat the entry to copy 00252 */ 00253 Entry(Entry::View vThat); 00254 00255 // ----- LocalCache::Entry interface ------------------------ 00256 00257 public: 00258 /** 00259 * Determine if the cache entry has expired. 00260 * 00261 * @return true if the cache entry was subject to automatic 00262 * expiry and the current time is greater than the 00263 * entry's expiry time 00264 */ 00265 virtual bool isExpired() const; 00266 00267 /** 00268 * Calculate a cache priority. 00269 * 00270 * @return a value between 0 and 10, 0 being the highest 00271 * priority 00272 */ 00273 virtual int32_t getPriority() const; 00274 00275 protected: 00276 /** 00277 * Called to inform the Entry that it is no longer used. 00278 */ 00279 virtual void discard(); 00280 00281 /** 00282 * Determine if this entry has already been discarded from the 00283 * cache. 00284 * 00285 * @return true if this entry has been discarded 00286 */ 00287 virtual bool isDiscarded(); 00288 00289 /** 00290 * Reschedule the cache entry expiration. 00291 */ 00292 virtual void scheduleExpiry(); 00293 00294 /** 00295 * Called each time the entry is accessed or modified. 00296 */ 00297 virtual void touch(); 00298 00299 /** 00300 * Reset the number of times that the cache entry has been 00301 * touched. The touch count does not get reset to zero, but 00302 * rather to a fraction of its former self; this prevents long 00303 * lived items from gaining an unassailable advantage in the 00304 * eviction process. 00305 * 00306 * @since Coherence 3.5 00307 */ 00308 virtual void resetTouchCount(); 00309 00310 // ----- SafeHashMap::Entry interface ----------------------- 00311 00312 public: 00313 /** 00314 * {@inheritDoc} 00315 */ 00316 virtual void onAdd(); 00317 00318 /** 00319 * {@inheritDoc} 00320 */ 00321 virtual Object::Holder setValue(Object::Holder ohValue); 00322 00323 // ----- helper methods ------------------------------------- 00324 00325 protected: 00326 /** 00327 * Calculate a cache cost for the specified object. 00328 * 00329 * The default implementation uses the unit calculator type 00330 * of the containing cache. 00331 * 00332 * @param ohValue the cache value to evaluate for unit cost 00333 * 00334 * @return an integer value 0 or greater, with a larger value 00335 * signifying a higher cost 00336 */ 00337 virtual size32_t calculateUnits(Object::Holder ohValue); 00338 00339 // ----- Object interface ----------------------------------- 00340 00341 public: 00342 /** 00343 * {@inheritDoc} 00344 */ 00345 virtual TypedHandle<const String> toString() const; 00346 00347 00348 // ----- accessors ------------------------------------------ 00349 00350 public: 00351 /** 00352 * Determine when the cache entry was created. 00353 * 00354 * @return the date/time value, in millis, when the entry was 00355 * created 00356 */ 00357 virtual int64_t getCreatedMillis() const; 00358 00359 /** 00360 * Determine when the cache entry will expire, if ever. 00361 * 00362 * @return the date/time value, in millis, when the entry will 00363 * (or did) expire; zero indicates no expiry 00364 */ 00365 virtual int64_t getExpiryMillis() const; 00366 00367 /** 00368 * Determine when the cache entry was last touched. 00369 * 00370 * @return the date/time value, in millis, when the entry was 00371 * most recently touched 00372 */ 00373 virtual int64_t getLastTouchMillis() const; 00374 00375 /** 00376 * Determine the number of times that the cache entry has been 00377 * touched. 00378 * 00379 * @return the number of times that the cache entry has been 00380 * touched 00381 */ 00382 virtual int32_t getTouchCount() const; 00383 00384 /** 00385 * Determine the number of cache units used by this Entry. 00386 * 00387 * @return an integer value 0 or greater, with a larger value 00388 * signifying a higher cost; -1 implies that the Entry 00389 * has been discarded 00390 */ 00391 virtual size32_t getUnits() const; 00392 00393 /** 00394 * Specify when the cache entry will expire, or disable 00395 * expiry. Note that if the cache is configured for automatic 00396 * expiry, each subsequent update to this cache entry will 00397 * reschedule the expiry time. 00398 * 00399 * @param lMillis pass the date/time value, in millis, for 00400 * when the entry will expire, or pass zero to 00401 * disable automatic expiry 00402 */ 00403 virtual void setExpiryMillis(int64_t lMillis); 00404 00405 /** 00406 * Specify the number of cache units used by this Entry. 00407 * 00408 * @param cUnits an integer value 0 or greater, with a larger 00409 * value 00410 */ 00411 virtual void setUnits(int32_t cUnits); 00412 00413 private: 00414 /** 00415 * Package Private: Obtain the next cache entry in the chain of 00416 * cache entries for a given hash bucket. 00417 * 00418 * @return the next cache entry in the hash bucket 00419 */ 00420 Entry::Handle getNext(); 00421 00422 /** 00423 * Package Private: Obtain the next cache entry in the chain of 00424 * cache entries for a given hash bucket. 00425 * 00426 * @return the next cache entry in the hash bucket 00427 */ 00428 Entry::View getNext() const; 00429 00430 /** 00431 * Specify the next cache entry in the chain of cache entries 00432 * for a given hash bucket. 00433 * 00434 * @param hEntry the next cache entry 00435 */ 00436 void setNext(SafeHashMap::Entry::Handle hEntry); 00437 00438 /** 00439 * Determine the most significant bit of the passed integral 00440 * value. 00441 * 00442 * @param n an int 00443 * 00444 * @return -1 if no bits are set; otherwise, the bit position 00445 * <tt>p</tt> of the most significant bit such that 00446 * <tt>1 << p</tt> is the most significant bit 00447 * of <tt>n</tt> 00448 */ 00449 int32_t indexOfMSB(size32_t n) const; 00450 00451 // ----- data members --------------------------------------- 00452 00453 protected: 00454 /** 00455 * The time at which this entry was created 00456 */ 00457 Volatile<int64_t> m_dtCreated; 00458 00459 /** 00460 * The time at which this Entry was last accessed. 00461 */ 00462 Volatile<int64_t> m_dtLastUse; 00463 00464 /** 00465 * The time at which this Entry will (or did) expire. 00466 */ 00467 Volatile<int64_t> m_dtExpiry; 00468 00469 /** 00470 * The number of times that this Entry has been accessed. 00471 */ 00472 int32_t m_cUses; 00473 00474 /** 00475 * The number of units for the Entry. 00476 */ 00477 size32_t m_cUnits; 00478 00479 /** 00480 * Reference back to the original cache. 00481 */ 00482 mutable FinalHandle<OldCache> f_hCache; 00483 00484 friend class OldCache::KeySet; 00485 friend class OldCache; 00486 friend class OldCache::ValuesCollection; 00487 }; 00488 00489 /** 00490 * {@inheritDoc} 00491 */ 00492 virtual SafeHashMap::Entry::Handle instantiateEntry( 00493 Object::View vKey, Object::Holder ohValue, 00494 size32_t nHash); 00495 00496 /** 00497 * {@inheritDoc} 00498 */ 00499 virtual SafeHashMap::Entry::Handle instantiateEntry( 00500 SafeHashMap::Entry::View vThat); 00501 00502 00503 // ----- inner class: IteratorFilter ------------------------------------ 00504 00505 protected: 00506 /** 00507 * This iterator will filter out expired entries from the result set 00508 * and expire them. 00509 */ 00510 class IteratorFilter 00511 : public class_spec<IteratorFilter, 00512 extends<Object>, 00513 implements<Filter> > 00514 { 00515 friend class factory<IteratorFilter>; 00516 00517 // ----- constructors --------------------------------------- 00518 00519 protected: 00520 /** 00521 * @internal 00522 */ 00523 IteratorFilter(OldCache::Holder thCache); 00524 00525 // ----- Filter interface ----------------------------------- 00526 00527 public: 00528 /** 00529 * Apply the test to the object. 00530 * 00531 * @param v the object to test 00532 * 00533 * @return true if the test passes, false otherwise 00534 */ 00535 virtual bool evaluate(Object::View v) const; 00536 00537 // ----- data members --------------------------------------- 00538 00539 protected: 00540 FinalHolder<OldCache> f_thCache; 00541 }; 00542 00543 00544 // ----- inner class: EntrySet ----------------------------------------- 00545 00546 protected: 00547 /** 00548 * A set of entries backed by this map. 00549 */ 00550 class EntrySet 00551 : public class_spec<EntrySet, 00552 extends<SafeHashMap::EntrySet> > 00553 { 00554 friend class factory<EntrySet>; 00555 00556 // ----- constructor ---------------------------------------- 00557 00558 protected: 00559 /** 00560 * @internal 00561 */ 00562 EntrySet(SafeHashMap::Handle hMap); 00563 00564 /** 00565 * @internal 00566 */ 00567 EntrySet(SafeHashMap::View vMap); 00568 00569 private: 00570 /** 00571 * @internal 00572 */ 00573 EntrySet(const Entry& that); 00574 00575 // ----- Set interface -------------------------------------- 00576 00577 public: 00578 /** 00579 * {@inheritDoc} 00580 */ 00581 virtual Iterator::Handle iterator() const; 00582 00583 /** 00584 * {@inheritDoc} 00585 */ 00586 virtual Muterator::Handle iterator(); 00587 00588 /** 00589 * {@inheritDoc} 00590 */ 00591 virtual ObjectArray::Handle toArray( 00592 ObjectArray::Handle hao = NULL) const; 00593 }; 00594 00595 /** 00596 * {@inheritDoc} 00597 */ 00598 virtual Set::Handle instantiateEntrySet(); 00599 00600 /** 00601 * {@inheritDoc} 00602 */ 00603 virtual Set::View instantiateEntrySet() const; 00604 00605 00606 // ----- inner class: KeySet -------------------------------------------- 00607 00608 protected: 00609 /** 00610 * A set of entries backed by this map. 00611 */ 00612 class KeySet 00613 : public class_spec<KeySet, 00614 extends<MapKeySet> > 00615 { 00616 friend class factory<KeySet>; 00617 00618 // ----- constructor ---------------------------------------- 00619 00620 protected: 00621 /** 00622 * @internal 00623 */ 00624 KeySet(SafeHashMap::Handle hMap); 00625 00626 /** 00627 * @internal 00628 */ 00629 KeySet(SafeHashMap::View vMap); 00630 00631 00632 // ----- Set interface -------------------------------------- 00633 00634 protected: 00635 /** 00636 * {@inheritDoc} 00637 */ 00638 virtual ObjectArray::Handle toArray( 00639 ObjectArray::Handle hoa = NULL) const; 00640 }; 00641 00642 /** 00643 * {@inheritDoc} 00644 */ 00645 virtual Set::Handle instantiateKeySet(); 00646 00647 /** 00648 * {@inheritDoc} 00649 */ 00650 virtual Set::View instantiateKeySet() const; 00651 00652 00653 // ----- inner class: ValuesCollection ---------------------------------- 00654 00655 protected: 00656 /** 00657 * A set of entries backed by this map. 00658 */ 00659 class ValuesCollection 00660 : public class_spec<ValuesCollection, 00661 extends<MapValuesCollection> > 00662 { 00663 friend class factory<ValuesCollection>; 00664 00665 // ----- constructor ---------------------------------------- 00666 00667 protected: 00668 /** 00669 * @internal 00670 */ 00671 ValuesCollection(SafeHashMap::Handle hMap); 00672 00673 /** 00674 * @internal 00675 */ 00676 ValuesCollection(SafeHashMap::View vMap); 00677 00678 // ----- Collection interface ------------------------------- 00679 00680 public: 00681 /** 00682 * {@inheritDoc} 00683 */ 00684 virtual ObjectArray::Handle toArray( 00685 ObjectArray::Handle hoa = NULL) const; 00686 }; 00687 00688 /** 00689 * {@inheritDoc} 00690 */ 00691 virtual Collection::Handle instantiateValuesCollection(); 00692 00693 /** 00694 * {@inheritDoc} 00695 */ 00696 virtual Collection::View instantiateValuesCollection() const; 00697 00698 00699 // ----- ObservableMap interface ---------------------------------------- 00700 00701 public: 00702 /** 00703 * {@inheritDoc} 00704 */ 00705 virtual void addKeyListener(MapListener::Handle hListener, 00706 Object::View vKey, bool fLite); 00707 00708 /** 00709 * {@inheritDoc} 00710 */ 00711 virtual void removeKeyListener(MapListener::Handle hListener, 00712 Object::View vKey); 00713 00714 /** 00715 * {@inheritDoc} 00716 */ 00717 virtual void addMapListener(MapListener::Handle hListener); 00718 00719 /** 00720 * {@inheritDoc} 00721 */ 00722 virtual void removeMapListener(MapListener::Handle hListener); 00723 00724 /** 00725 * {@inheritDoc} 00726 */ 00727 virtual void addFilterListener(MapListener::Handle hListener, 00728 Filter::View vFilter = NULL, bool fLite = false); 00729 00730 /** 00731 * {@inheritDoc} 00732 */ 00733 virtual void removeFilterListener(MapListener::Handle hListener, 00734 Filter::View vFilter = NULL); 00735 00736 00737 // ----- Map interface -------------------------------------------------- 00738 00739 public: 00740 /** 00741 * {@inheritDoc} 00742 */ 00743 virtual bool isEmpty() const; 00744 00745 /** 00746 * {@inheritDoc} 00747 */ 00748 virtual size32_t size() const; 00749 00750 /** 00751 * {@inheritDoc} 00752 */ 00753 virtual bool containsKey(Object::View vKey) const; 00754 00755 /** 00756 * {@inheritDoc} 00757 */ 00758 virtual Object::Holder get(Object::View vKey) const; 00759 00760 /** 00761 * {@inheritDoc} 00762 */ 00763 using Map::get; 00764 00765 /** 00766 * {@inheritDoc} 00767 */ 00768 virtual Object::Holder put(Object::View vKey, Object::Holder ohValue); 00769 00770 /** 00771 * {@inheritDoc} 00772 */ 00773 virtual Object::Holder remove(Object::View vKey); 00774 using Map::remove; 00775 00776 /** 00777 * {@inheritDoc} 00778 */ 00779 virtual void clear(); 00780 00781 00782 // ----- CacheMap interface --------------------------------------------- 00783 public: 00784 /** 00785 * {@inheritDoc} 00786 */ 00787 virtual Object::Holder put(Object::View vKey, Object::Holder ohValue, 00788 int64_t cMillis); 00789 00790 /** 00791 * {@inheritDoc} 00792 */ 00793 virtual Map::View getAll(Collection::View vColKeys) const; 00794 00795 00796 // ----- Cache management methods --------------------------------------- 00797 00798 public: 00799 /** 00800 * Release local resources associated with the Cache. 00801 * 00802 * Releasing a cache makes it no longer usable 00803 */ 00804 virtual void release(); 00805 00806 /** 00807 * Evict a specified key from the cache, as if it had expired from the 00808 * cache. If the key is not in the cache, then the method has no effect. 00809 * 00810 * @param oKey the key to evict from the cache 00811 */ 00812 virtual void evict(Object::View vKey); 00813 00814 /** 00815 * Evict the specified keys from the cache, as if they had each expired 00816 * from the cache. 00817 * 00818 * The result of this method is defined to be semantically the same as 00819 * the following implementation: 00820 * 00821 * <tt> 00822 * for (Iterator iter = colKeys.iterator(); iter.hasNext(); ) 00823 * { 00824 * Object oKey = iter.next(); 00825 * evict(oKey); 00826 * } 00827 * </tt> 00828 * 00829 * @param colKeys a collection of keys to evict from the cache 00830 */ 00831 virtual void evictAll(Collection::View vColKeys); 00832 00833 /** 00834 * Evict all entries from the cache that are no longer valid, and 00835 * potentially prune the cache size if the cache is size-limited 00836 * and its size is above the caching low water mark. 00837 */ 00838 virtual void evict(); 00839 00840 /** 00841 * Returns the CacheStatistics for this cache. 00842 * 00843 * @return a CacheStatistics object 00844 */ 00845 virtual CacheStatistics::View getCacheStatistics() const; 00846 00847 /** 00848 * Returns the CacheStatistics for this cache. 00849 * 00850 * @return a CacheStatistics object 00851 */ 00852 virtual CacheStatistics::Handle getCacheStatistics(); 00853 00854 /** 00855 * Determine the number of units that the cache currently stores. 00856 * 00857 * @return the current size of the cache in units 00858 */ 00859 virtual size32_t getUnits() const; 00860 00861 /** 00862 * Determine the limit of the cache size in units. The cache will prune 00863 * itself automatically once it reaches its maximum unit level. This is 00864 * often referred to as the "high water mark" of the cache. 00865 * 00866 * @return the limit of the cache size in units 00867 */ 00868 virtual size32_t getHighUnits() const; 00869 00870 /** 00871 * Update the maximum size of the cache in units. This is often referred 00872 * to as the "high water mark" of the cache. 00873 * 00874 * @param cMax the new maximum size of the cache, in units 00875 */ 00876 virtual void setHighUnits(size32_t cMax); 00877 00878 /** 00879 * Determine the point to which the cache will shrink when it prunes. 00880 * This is often referred to as a "low water mark" of the cache. 00881 * 00882 * @return the number of units that the cache prunes to 00883 */ 00884 virtual size32_t getLowUnits() const; 00885 00886 /** 00887 * Specify the point to which the cache will shrink when it prunes. 00888 * This is often referred to as a "low water mark" of the cache. 00889 * 00890 * @param cUnits the number of units that the cache prunes to 00891 */ 00892 virtual void setLowUnits(size32_t cUnits); 00893 00894 /** 00895 * Determine the current eviction type. 00896 * 00897 * @return one of the EVICTION_POLICY_* enumerated values 00898 */ 00899 virtual EvictionPolicy::EvictionPolicyType getEvictionType() const; 00900 00901 /** 00902 * Specify the eviction type for the cache. The type can only be 00903 * set to an external policy if an EvictionPolicy object has been 00904 * provided. 00905 * 00906 * @param nType one of the EVICTION_POLICY_* enumerated values 00907 */ 00908 virtual void setEvictionType(EvictionPolicy::EvictionPolicyType nType); 00909 00910 /** 00911 * Determine the current external eviction policy, if any. 00912 * 00913 * @return the external eviction policy, if one has been 00914 * provided 00915 */ 00916 virtual EvictionPolicy::View getEvictionPolicy() const; 00917 00918 /** 00919 * Determine the current external eviction policy, if any. 00920 * 00921 * @return the external eviction policy, if one has been provided 00922 */ 00923 virtual EvictionPolicy::Handle getEvictionPolicy(); 00924 00925 /** 00926 * Set the external eviction policy, and change the eviction type to 00927 * eviction_policy_external. If null is passed, clear the external 00928 * eviction policy, and use the default internal policy. 00929 * 00930 * @param policy an external eviction policy, or null to use the default 00931 * policy 00932 */ 00933 virtual void setEvictionPolicy(EvictionPolicy::Handle hPolicy); 00934 00935 /** 00936 * Determine the current unit calculator type. 00937 * 00938 * @return one of the UNIT_CALCULATOR_* enumerated values 00939 */ 00940 virtual UnitCalculatorType getUnitCalculatorType() const; 00941 00942 /** 00943 * Specify the unit calculator type for the cache. The type can only be 00944 * set to an external unit calculator if a UnitCalculator object has been 00945 * provided. 00946 * 00947 * @param nType one of the UNIT_CALCULATOR_* enumerated values 00948 */ 00949 virtual void setUnitCalculatorType(UnitCalculatorType nType); 00950 00951 /** 00952 * Determine the current external unit calculator, if any. 00953 * 00954 * @return the external unit calculator, if one has been provided 00955 */ 00956 virtual UnitCalculator::View getUnitCalculator() const; 00957 00958 /** 00959 * Set the external unit calculator, and change the unit calculator type to 00960 * unit_calculator_external. If null is passed, clear the external 00961 * unit calculator, and use the default unit calculator. 00962 * 00963 * @param calculator an external unit calculator, or null to use the default 00964 * unit calculator 00965 */ 00966 virtual void setUnitCalculator(UnitCalculator::Handle hCalculator); 00967 00968 /** 00969 * Determine the "time to live" for each individual cache entry. 00970 * 00971 * @return the number of milliseconds that a cache entry value will live, 00972 * or zero if cache entries are never automatically expired 00973 */ 00974 virtual int32_t getExpiryDelay() const; 00975 00976 /** 00977 * Specify the "time to live" for cache entries. This does not affect 00978 * the already-scheduled expiry of existing entries. 00979 * 00980 * @param cMillis the number of milliseconds that cache entries will 00981 * live, or zero to disable automatic expiry 00982 */ 00983 virtual void setExpiryDelay(int cMillis); 00984 00985 /** 00986 * Determine the delay between cache flushes. 00987 * 00988 * @return the number of milliseconds between cache flushes, or zero which 00989 * signifies that the cache never flushes 00990 */ 00991 virtual int32_t getFlushDelay() const; 00992 00993 /** 00994 * Specify the delay between cache flushes. 00995 * 00996 * @param cMillis the number of milliseconds between cache flushes, or 00997 * zero to never flush 00998 */ 00999 virtual void setFlushDelay(int32_t cMillis); 01000 01001 /** 01002 * Determine the date/time at which the next cache flush is scheduled. 01003 * Note that the date/time may be Long.max_value, which implies that a 01004 * flush will never occur. Also note that the cache may internally adjust 01005 * the flush time to prevent a flush from occurring during certain 01006 * processing as a means to raise concurrency. 01007 * 01008 * @return the date/time value, in milliseconds, when the cache will next 01009 * automatically flush 01010 */ 01011 virtual int64_t getFlushTime() const; 01012 01013 /** 01014 * Specify the date/time at which the next cache flush is to occur. 01015 * Note that the date/time may be Long.max_value, which implies that a 01016 * flush will never occur. A time in the past or at the present will 01017 * cause an immediate flush. 01018 * 01019 * @param lMillis the date/time value, in milliseconds, when the cache 01020 * should next automatically flush 01021 */ 01022 virtual void setFlushTime(int64_t lMillis); 01023 01024 /** 01025 * Specify if the cache is allowed to hold mutable values. 01026 * 01027 * If false the cache will ensure immutability before caching any value. 01028 * 01029 * @param fAllow true if the cache is allowed to hold mutable values 01030 */ 01031 virtual void setAllowMutableValues(bool fAllow); 01032 01033 /** 01034 * Return whether the cache is allowed to hold mutable values. 01035 * 01036 * If false the cache will ensure immutability before caching any value. 01037 * 01038 * @return true if the cache is allowed to hold mutable values 01039 */ 01040 virtual bool isAllowMutableValues() const; 01041 01042 // ----- statistics ----------------------------------------------------- 01043 01044 public: 01045 /** 01046 * Determine the rough number of cache hits since the cache statistics 01047 * were last reset. 01048 * 01049 * @return the number of {@link #get} calls that have been served by 01050 * existing cache entries 01051 */ 01052 virtual int64_t getCacheHits() const; 01053 01054 /** 01055 * Determine the rough number of cache misses since the cache statistics 01056 * were last reset. 01057 * 01058 * @return the number of {@link #get} calls that failed to find an 01059 * existing cache entry because the requested key was not in the 01060 * cache 01061 */ 01062 virtual int64_t getCacheMisses() const; 01063 01064 /** 01065 * Determine the rough probability (0 <= p <= 1) that any particular 01066 * {@link #get} invocation will be satisfied by an existing entry in 01067 * the cache, based on the statistics collected since the last reset 01068 * of the cache statistics. 01069 * 01070 * @return the cache hit probability (0 <= p <= 1) 01071 */ 01072 virtual float64_t getHitProbability() const; 01073 01074 /** 01075 * Reset the cache statistics. 01076 */ 01077 virtual void resetHitStatistics(); 01078 01079 01080 // ----- Object interface ----------------------------------------------- 01081 01082 public: 01083 /** 01084 * {@inheritDoc} 01085 */ 01086 virtual TypedHandle<const String> toString() const; 01087 01088 01089 // ----- helper methods ------------------------------------------------- 01090 01091 public: 01092 /** 01093 * {@inheritDoc} 01094 */ 01095 virtual SafeHashMap::Entry::View getEntry(Object::View vKey) const; 01096 01097 /** 01098 * {@inheritDoc} 01099 */ 01100 virtual SafeHashMap::Entry::Handle getEntry(Object::View vKey); 01101 01102 protected: 01103 /** 01104 * Configure the eviction type and policy. 01105 * 01106 * @param nType one of the EVICTION_POLICY_* enumerated values 01107 * @param hPolicy an external eviction policy, or null 01108 */ 01109 virtual void configureEviction(EvictionPolicy::EvictionPolicyType nType, 01110 EvictionPolicy::Handle hPolicy); 01111 01112 /** 01113 * Configure the unit calculator type and implementation. 01114 * 01115 * @param nType one of the UNIT_CALCULATOR_* enumerated values 01116 * @param hCalculator an external unit calculator, or null 01117 */ 01118 virtual void configureUnitCalculator(UnitCalculatorType nType, 01119 UnitCalculator::Handle hCalculator); 01120 01121 /** 01122 * Locate an Entry in the hash map based on its key. If the Entry has 01123 * expired, it is removed from the hash map. 01124 * 01125 * Unlike the {@link #getEntry} method, this method does not flush the cache 01126 * (if necessary) or update cache statistics. 01127 * 01128 * @param oKey the key object to search for 01129 * 01130 * @return the Entry or null if the entry is not found in the hash map or 01131 * has expired 01132 */ 01133 virtual SafeHashMap::Entry::Handle getEntryInternal(Object::View vKey) const; 01134 01135 /** 01136 * Check if the cache is timed out, and clear if it is. 01137 */ 01138 virtual void checkFlush() const; 01139 01140 /** 01141 * Check if the cache is timed out, and clear if it is. 01142 */ 01143 virtual void checkFlush(); 01144 01145 /** 01146 * Remove an entry because it has expired. 01147 * 01148 * @param vEntry the expired cache entry 01149 * @param fRemoveInternal true if the cache entry still needs to be 01150 * removed from the cache 01151 */ 01152 virtual void removeExpired(Entry::View vEntry, bool fRemoveInternal) const; 01153 01154 /** 01155 * Remove an entry because it has expired. 01156 * 01157 * @param hEntry the expired cache entry 01158 * @param fRemoveInternal true if the cache entry still needs to be 01159 * removed from the cache 01160 */ 01161 virtual void removeExpired(Entry::Handle hEntry, bool fRemoveInternal); 01162 01163 /** 01164 * Increment the current size 01165 */ 01166 virtual void incrementUnits(size32_t cDelta); 01167 01168 /** 01169 * Decrement the current size 01170 */ 01171 virtual void decrementUnits(size32_t cDelta); 01172 01173 /** 01174 * Check if the cache is too big, and if it is prune it by discarding the 01175 * lowest priority cache entries. 01176 */ 01177 virtual void checkSize(); 01178 01179 /** 01180 * Prune the cache by discarding the lowest priority cache entries. 01181 */ 01182 virtual void prune(); 01183 01184 /** 01185 * Defer the next flush by scheduling it for infinity and beyond. 01186 */ 01187 virtual void deferFlush(); 01188 01189 /** 01190 * Schedule the next flush. 01191 */ 01192 virtual void scheduleFlush(); 01193 01194 /** 01195 * Factory pattern: instantiate a new MapEvent corresponding 01196 * to the specified parameters. 01197 * 01198 * @return a new instance of the MapEvent class (or a subclass thereof) 01199 */ 01200 virtual MapEvent::Handle instantiateMapEvent( 01201 int32_t nId, Object::View vKey, Object::Holder ohValueOld, Object::Holder ohValueNew); 01202 01203 01204 // ----- event dispatching ---------------------------------------------- 01205 01206 protected: 01207 /** 01208 * Accessor for the MapListenerSupport for sub-classes. 01209 * 01210 * @return the MapListenerSupport, or null if there are no listeners 01211 */ 01212 virtual MapListenerSupport::Handle getMapListenerSupport(); 01213 01214 /** 01215 * Determine if the OverflowMap has any listeners at all. 01216 * 01217 * @return true iff this OverflowMap has at least one MapListener 01218 */ 01219 virtual bool hasListeners(); 01220 01221 /** 01222 * Dispatch the passed event. 01223 * 01224 * @param hEvt a CacheEvent object 01225 */ 01226 virtual void dispatchEvent(MapEvent::Handle hEvt); 01227 01228 01229 // ----- data members --------------------------------------------------- 01230 01231 protected: 01232 /** 01233 * The current number of units in the cache. A unit is an undefined means 01234 * of measuring cached values, and must be 0 or positive. The particular 01235 * Entry implementation being used defines the meaning of unit. 01236 */ 01237 size32_t m_cCurUnits; 01238 01239 /** 01240 * The number of units to allow the cache to grow to before pruning. 01241 */ 01242 size32_t m_cMaxUnits; 01243 01244 /** 01245 * The percentage of the total number of units that will remain after 01246 * the cache manager prunes the cache (i.e. this is the "low water 01247 * mark" value); this value is in the range 0.0 to 1.0. 01248 */ 01249 float64_t m_dflPruneLevel; 01250 01251 /** 01252 * The number of units to prune the cache down to. 01253 */ 01254 size32_t m_cPruneUnits; 01255 01256 /** 01257 * The number of milliseconds that a value will live in the cache. 01258 * Zero indicates no timeout. 01259 */ 01260 size32_t m_cExpiryDelay; 01261 01262 /** 01263 * The interval between full cache flushes, in milliseconds. 01264 */ 01265 int32_t m_cFlushDelay; 01266 01267 /** 01268 * The time (ie System.currentTimeMillis) at which the next full cache 01269 * flush should occur. 01270 */ 01271 Volatile<int64_t> m_lNextFlush; 01272 01273 /** 01274 * The CacheStatistics object maintained by this cache. 01275 */ 01276 mutable FinalHandle<SimpleCacheStatistics> f_hStats; 01277 01278 /** 01279 * The MapListenerSupport object. 01280 */ 01281 MemberHandle<MapListenerSupport> m_hListenerSupport; 01282 01283 /** 01284 * The type of eviction policy employed by the cache; one of the 01285 * EVICTION_POLICY_* enumerated values. 01286 */ 01287 EvictionPolicy::EvictionPolicyType m_nEvictionType; 01288 01289 /** 01290 * The eviction policy; for eviction type eviction_policy_external. 01291 */ 01292 MemberHandle<EvictionPolicy> m_hPolicy; 01293 01294 /** 01295 * The type of unit calculator employed by the cache; one of the 01296 * UNIT_CALCULATOR_* enumerated values. 01297 */ 01298 UnitCalculatorType m_CalculatorType; 01299 01300 /** 01301 * The external unit calculator. 01302 */ 01303 MemberView<UnitCalculator> m_vCalculator; 01304 01305 /** 01306 * The last time that a prune was run. This value is used by the 01307 * hybrid eviction policy. 01308 * @since Coherence 3.5 01309 */ 01310 int64_t m_lLastPrune; 01311 01312 /** 01313 * For a prune cycle, this value is the average number of touches that 01314 * an entry should have. This value is used by the hybrid eviction 01315 * policy. 01316 * @since Coherence 3.5 01317 */ 01318 size32_t m_cAvgTouch; 01319 01320 /** 01321 * Allow mutable values. 01322 */ 01323 bool m_fAllowMutableValues; 01324 01325 // ----- friends -------------------------------------------------------- 01326 01327 friend class IteratorFilter; 01328 friend class KeySet; 01329 }; 01330 01331 COH_CLOSE_NAMESPACE3 01332 01333 #endif // COH_LOCAL_CACHE_HPP