00001 /* 00002 * OldCache.hpp 00003 * 00004 * Copyright (c) 2000, 2014, 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 #include <ostream> 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 void toStream(std::ostream& out) 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 size32_t size() const; 00744 00745 /** 00746 * {@inheritDoc} 00747 */ 00748 virtual bool containsKey(Object::View vKey) const; 00749 00750 /** 00751 * {@inheritDoc} 00752 */ 00753 virtual Object::Holder get(Object::View vKey) const; 00754 00755 /** 00756 * {@inheritDoc} 00757 */ 00758 using Map::get; 00759 00760 /** 00761 * {@inheritDoc} 00762 */ 00763 virtual Object::Holder put(Object::View vKey, Object::Holder ohValue); 00764 00765 /** 00766 * {@inheritDoc} 00767 */ 00768 virtual Object::Holder remove(Object::View vKey); 00769 00770 /** 00771 * {@inheritDoc} 00772 */ 00773 virtual void clear(); 00774 00775 00776 // ----- CacheMap interface --------------------------------------------- 00777 public: 00778 /** 00779 * {@inheritDoc} 00780 */ 00781 virtual Object::Holder put(Object::View vKey, Object::Holder ohValue, 00782 int64_t cMillis); 00783 00784 /** 00785 * {@inheritDoc} 00786 */ 00787 virtual Map::View getAll(Collection::View vColKeys) const; 00788 00789 00790 // ----- Cache management methods --------------------------------------- 00791 00792 public: 00793 /** 00794 * Release local resources associated with the Cache. 00795 * 00796 * Releasing a cache makes it no longer usable 00797 */ 00798 virtual void release(); 00799 00800 /** 00801 * Evict a specified key from the cache, as if it had expired from the 00802 * cache. If the key is not in the cache, then the method has no effect. 00803 * 00804 * @param oKey the key to evict from the cache 00805 */ 00806 virtual void evict(Object::View vKey); 00807 00808 /** 00809 * Evict the specified keys from the cache, as if they had each expired 00810 * from the cache. 00811 * 00812 * The result of this method is defined to be semantically the same as 00813 * the following implementation: 00814 * 00815 * <tt> 00816 * for (Iterator iter = colKeys.iterator(); iter.hasNext(); ) 00817 * { 00818 * Object oKey = iter.next(); 00819 * evict(oKey); 00820 * } 00821 * </tt> 00822 * 00823 * @param colKeys a collection of keys to evict from the cache 00824 */ 00825 virtual void evictAll(Collection::View vColKeys); 00826 00827 /** 00828 * Evict all entries from the cache that are no longer valid, and 00829 * potentially prune the cache size if the cache is size-limited 00830 * and its size is above the caching low water mark. 00831 */ 00832 virtual void evict(); 00833 00834 /** 00835 * Returns the CacheStatistics for this cache. 00836 * 00837 * @return a CacheStatistics object 00838 */ 00839 virtual CacheStatistics::View getCacheStatistics() const; 00840 00841 /** 00842 * Returns the CacheStatistics for this cache. 00843 * 00844 * @return a CacheStatistics object 00845 */ 00846 virtual CacheStatistics::Handle getCacheStatistics(); 00847 00848 /** 00849 * Determine the number of units that the cache currently stores. 00850 * 00851 * @return the current size of the cache in units 00852 */ 00853 virtual size32_t getUnits() const; 00854 00855 /** 00856 * Determine the limit of the cache size in units. The cache will prune 00857 * itself automatically once it reaches its maximum unit level. This is 00858 * often referred to as the "high water mark" of the cache. 00859 * 00860 * @return the limit of the cache size in units 00861 */ 00862 virtual size32_t getHighUnits() const; 00863 00864 /** 00865 * Update the maximum size of the cache in units. This is often referred 00866 * to as the "high water mark" of the cache. 00867 * 00868 * @param cMax the new maximum size of the cache, in units 00869 */ 00870 virtual void setHighUnits(size32_t cMax); 00871 00872 /** 00873 * Determine the point to which the cache will shrink when it prunes. 00874 * This is often referred to as a "low water mark" of the cache. 00875 * 00876 * @return the number of units that the cache prunes to 00877 */ 00878 virtual size32_t getLowUnits() const; 00879 00880 /** 00881 * Specify the point to which the cache will shrink when it prunes. 00882 * This is often referred to as a "low water mark" of the cache. 00883 * 00884 * @param cUnits the number of units that the cache prunes to 00885 */ 00886 virtual void setLowUnits(size32_t cUnits); 00887 00888 /** 00889 * Determine the current eviction type. 00890 * 00891 * @return one of the EVICTION_POLICY_* enumerated values 00892 */ 00893 virtual EvictionPolicy::EvictionPolicyType getEvictionType() const; 00894 00895 /** 00896 * Specify the eviction type for the cache. The type can only be 00897 * set to an external policy if an EvictionPolicy object has been 00898 * provided. 00899 * 00900 * @param nType one of the EVICTION_POLICY_* enumerated values 00901 */ 00902 virtual void setEvictionType(EvictionPolicy::EvictionPolicyType nType); 00903 00904 /** 00905 * Determine the current external eviction policy, if any. 00906 * 00907 * @return the external eviction policy, if one has been 00908 * provided 00909 */ 00910 virtual EvictionPolicy::View getEvictionPolicy() const; 00911 00912 /** 00913 * Determine the current external eviction policy, if any. 00914 * 00915 * @return the external eviction policy, if one has been provided 00916 */ 00917 virtual EvictionPolicy::Handle getEvictionPolicy(); 00918 00919 /** 00920 * Set the external eviction policy, and change the eviction type to 00921 * eviction_policy_external. If null is passed, clear the external 00922 * eviction policy, and use the default internal policy. 00923 * 00924 * @param policy an external eviction policy, or null to use the default 00925 * policy 00926 */ 00927 virtual void setEvictionPolicy(EvictionPolicy::Handle hPolicy); 00928 00929 /** 00930 * Determine the current unit calculator type. 00931 * 00932 * @return one of the UNIT_CALCULATOR_* enumerated values 00933 */ 00934 virtual UnitCalculatorType getUnitCalculatorType() const; 00935 00936 /** 00937 * Specify the unit calculator type for the cache. The type can only be 00938 * set to an external unit calculator if a UnitCalculator object has been 00939 * provided. 00940 * 00941 * @param nType one of the UNIT_CALCULATOR_* enumerated values 00942 */ 00943 virtual void setUnitCalculatorType(UnitCalculatorType nType); 00944 00945 /** 00946 * Determine the current external unit calculator, if any. 00947 * 00948 * @return the external unit calculator, if one has been provided 00949 */ 00950 virtual UnitCalculator::View getUnitCalculator() const; 00951 00952 /** 00953 * Set the external unit calculator, and change the unit calculator type to 00954 * unit_calculator_external. If null is passed, clear the external 00955 * unit calculator, and use the default unit calculator. 00956 * 00957 * @param calculator an external unit calculator, or null to use the default 00958 * unit calculator 00959 */ 00960 virtual void setUnitCalculator(UnitCalculator::Handle hCalculator); 00961 00962 /** 00963 * Determine the "time to live" for each individual cache entry. 00964 * 00965 * @return the number of milliseconds that a cache entry value will live, 00966 * or zero if cache entries are never automatically expired 00967 */ 00968 virtual int32_t getExpiryDelay() const; 00969 00970 /** 00971 * Specify the "time to live" for cache entries. This does not affect 00972 * the already-scheduled expiry of existing entries. 00973 * 00974 * @param cMillis the number of milliseconds that cache entries will 00975 * live, or zero to disable automatic expiry 00976 */ 00977 virtual void setExpiryDelay(int cMillis); 00978 00979 /** 00980 * Determine the delay between cache flushes. 00981 * 00982 * @return the number of milliseconds between cache flushes, or zero which 00983 * signifies that the cache never flushes 00984 */ 00985 virtual int32_t getFlushDelay() const; 00986 00987 /** 00988 * Specify the delay between cache flushes. 00989 * 00990 * @param cMillis the number of milliseconds between cache flushes, or 00991 * zero to never flush 00992 */ 00993 virtual void setFlushDelay(int32_t cMillis); 00994 00995 /** 00996 * Determine the date/time at which the next cache flush is scheduled. 00997 * Note that the date/time may be Long.max_value, which implies that a 00998 * flush will never occur. Also note that the cache may internally adjust 00999 * the flush time to prevent a flush from occurring during certain 01000 * processing as a means to raise concurrency. 01001 * 01002 * @return the date/time value, in milliseconds, when the cache will next 01003 * automatically flush 01004 */ 01005 virtual int64_t getFlushTime() const; 01006 01007 /** 01008 * Specify the date/time at which the next cache flush is to occur. 01009 * Note that the date/time may be Long.max_value, which implies that a 01010 * flush will never occur. A time in the past or at the present will 01011 * cause an immediate flush. 01012 * 01013 * @param lMillis the date/time value, in milliseconds, when the cache 01014 * should next automatically flush 01015 */ 01016 virtual void setFlushTime(int64_t lMillis); 01017 01018 /** 01019 * Specify if the cache is allowed to hold mutable values. 01020 * 01021 * If false the cache will ensure immutability before caching any value. 01022 * 01023 * @param fAllow true if the cache is allowed to hold mutable values 01024 */ 01025 virtual void setAllowMutableValues(bool fAllow); 01026 01027 /** 01028 * Return whether the cache is allowed to hold mutable values. 01029 * 01030 * If false the cache will ensure immutability before caching any value. 01031 * 01032 * @return true if the cache is allowed to hold mutable values 01033 */ 01034 virtual bool isAllowMutableValues() const; 01035 01036 // ----- statistics ----------------------------------------------------- 01037 01038 public: 01039 /** 01040 * Determine the rough number of cache hits since the cache statistics 01041 * were last reset. 01042 * 01043 * @return the number of {@link #get} calls that have been served by 01044 * existing cache entries 01045 */ 01046 virtual int64_t getCacheHits() const; 01047 01048 /** 01049 * Determine the rough number of cache misses since the cache statistics 01050 * were last reset. 01051 * 01052 * @return the number of {@link #get} calls that failed to find an 01053 * existing cache entry because the requested key was not in the 01054 * cache 01055 */ 01056 virtual int64_t getCacheMisses() const; 01057 01058 /** 01059 * Determine the rough probability (0 <= p <= 1) that any particular 01060 * {@link #get} invocation will be satisfied by an existing entry in 01061 * the cache, based on the statistics collected since the last reset 01062 * of the cache statistics. 01063 * 01064 * @return the cache hit probability (0 <= p <= 1) 01065 */ 01066 virtual float64_t getHitProbability() const; 01067 01068 /** 01069 * Reset the cache statistics. 01070 */ 01071 virtual void resetHitStatistics(); 01072 01073 01074 // ----- Object interface ----------------------------------------------- 01075 01076 public: 01077 /** 01078 * {@inheritDoc} 01079 */ 01080 virtual void toStream(std::ostream& out) const; 01081 01082 01083 // ----- helper methods ------------------------------------------------- 01084 01085 public: 01086 /** 01087 * {@inheritDoc} 01088 */ 01089 virtual SafeHashMap::Entry::View getEntry(Object::View vKey) const; 01090 01091 /** 01092 * {@inheritDoc} 01093 */ 01094 virtual SafeHashMap::Entry::Handle getEntry(Object::View vKey); 01095 01096 protected: 01097 /** 01098 * Configure the eviction type and policy. 01099 * 01100 * @param nType one of the EVICTION_POLICY_* enumerated values 01101 * @param hPolicy an external eviction policy, or null 01102 */ 01103 virtual void configureEviction(EvictionPolicy::EvictionPolicyType nType, 01104 EvictionPolicy::Handle hPolicy); 01105 01106 /** 01107 * Configure the unit calculator type and implementation. 01108 * 01109 * @param nType one of the UNIT_CALCULATOR_* enumerated values 01110 * @param hCalculator an external unit calculator, or null 01111 */ 01112 virtual void configureUnitCalculator(UnitCalculatorType nType, 01113 UnitCalculator::Handle hCalculator); 01114 01115 /** 01116 * Locate an Entry in the hash map based on its key. If the Entry has 01117 * expired, it is removed from the hash map. 01118 * 01119 * Unlike the {@link #getEntry} method, this method does not flush the cache 01120 * (if necessary) or update cache statistics. 01121 * 01122 * @param oKey the key object to search for 01123 * 01124 * @return the Entry or null if the entry is not found in the hash map or 01125 * has expired 01126 */ 01127 virtual SafeHashMap::Entry::Handle getEntryInternal(Object::View vKey) const; 01128 01129 /** 01130 * Check if the cache is timed out, and clear if it is. 01131 */ 01132 virtual void checkFlush() const; 01133 01134 /** 01135 * Check if the cache is timed out, and clear if it is. 01136 */ 01137 virtual void checkFlush(); 01138 01139 /** 01140 * Remove an entry because it has expired. 01141 * 01142 * @param vEntry the expired cache entry 01143 * @param fRemoveInternal true if the cache entry still needs to be 01144 * removed from the cache 01145 */ 01146 virtual void removeExpired(Entry::View vEntry, bool fRemoveInternal) const; 01147 01148 /** 01149 * Remove an entry because it has expired. 01150 * 01151 * @param hEntry the expired cache entry 01152 * @param fRemoveInternal true if the cache entry still needs to be 01153 * removed from the cache 01154 */ 01155 virtual void removeExpired(Entry::Handle hEntry, bool fRemoveInternal); 01156 01157 /** 01158 * Increment the current size 01159 */ 01160 virtual void incrementUnits(size32_t cDelta); 01161 01162 /** 01163 * Decrement the current size 01164 */ 01165 virtual void decrementUnits(size32_t cDelta); 01166 01167 /** 01168 * Check if the cache is too big, and if it is prune it by discarding the 01169 * lowest priority cache entries. 01170 */ 01171 virtual void checkSize(); 01172 01173 /** 01174 * Prune the cache by discarding the lowest priority cache entries. 01175 */ 01176 virtual void prune(); 01177 01178 /** 01179 * Defer the next flush by scheduling it for infinity and beyond. 01180 */ 01181 virtual void deferFlush(); 01182 01183 /** 01184 * Schedule the next flush. 01185 */ 01186 virtual void scheduleFlush(); 01187 01188 /** 01189 * Factory pattern: instantiate a new MapEvent corresponding 01190 * to the specified parameters. 01191 * 01192 * @return a new instance of the MapEvent class (or a subclass thereof) 01193 */ 01194 virtual MapEvent::Handle instantiateMapEvent( 01195 int32_t nId, Object::View vKey, Object::Holder ohValueOld, Object::Holder ohValueNew); 01196 01197 01198 // ----- event dispatching ---------------------------------------------- 01199 01200 protected: 01201 /** 01202 * Accessor for the MapListenerSupport for sub-classes. 01203 * 01204 * @return the MapListenerSupport, or null if there are no listeners 01205 */ 01206 virtual MapListenerSupport::Handle getMapListenerSupport(); 01207 01208 /** 01209 * Determine if the OverflowMap has any listeners at all. 01210 * 01211 * @return true iff this OverflowMap has at least one MapListener 01212 */ 01213 virtual bool hasListeners(); 01214 01215 /** 01216 * Dispatch the passed event. 01217 * 01218 * @param hEvt a CacheEvent object 01219 */ 01220 virtual void dispatchEvent(MapEvent::Handle hEvt); 01221 01222 01223 // ----- data members --------------------------------------------------- 01224 01225 protected: 01226 /** 01227 * The current number of units in the cache. A unit is an undefined means 01228 * of measuring cached values, and must be 0 or positive. The particular 01229 * Entry implementation being used defines the meaning of unit. 01230 */ 01231 size32_t m_cCurUnits; 01232 01233 /** 01234 * The number of units to allow the cache to grow to before pruning. 01235 */ 01236 size32_t m_cMaxUnits; 01237 01238 /** 01239 * The percentage of the total number of units that will remain after 01240 * the cache manager prunes the cache (i.e. this is the "low water 01241 * mark" value); this value is in the range 0.0 to 1.0. 01242 */ 01243 float64_t m_dflPruneLevel; 01244 01245 /** 01246 * The number of units to prune the cache down to. 01247 */ 01248 size32_t m_cPruneUnits; 01249 01250 /** 01251 * The number of milliseconds that a value will live in the cache. 01252 * Zero indicates no timeout. 01253 */ 01254 size32_t m_cExpiryDelay; 01255 01256 /** 01257 * The interval between full cache flushes, in milliseconds. 01258 */ 01259 int32_t m_cFlushDelay; 01260 01261 /** 01262 * The time (ie System.currentTimeMillis) at which the next full cache 01263 * flush should occur. 01264 */ 01265 Volatile<int64_t> m_lNextFlush; 01266 01267 /** 01268 * The CacheStatistics object maintained by this cache. 01269 */ 01270 mutable FinalHandle<SimpleCacheStatistics> f_hStats; 01271 01272 /** 01273 * The MapListenerSupport object. 01274 */ 01275 MemberHandle<MapListenerSupport> m_hListenerSupport; 01276 01277 /** 01278 * The type of eviction policy employed by the cache; one of the 01279 * EVICTION_POLICY_* enumerated values. 01280 */ 01281 EvictionPolicy::EvictionPolicyType m_nEvictionType; 01282 01283 /** 01284 * The eviction policy; for eviction type eviction_policy_external. 01285 */ 01286 MemberHandle<EvictionPolicy> m_hPolicy; 01287 01288 /** 01289 * The type of unit calculator employed by the cache; one of the 01290 * UNIT_CALCULATOR_* enumerated values. 01291 */ 01292 UnitCalculatorType m_CalculatorType; 01293 01294 /** 01295 * The external unit calculator. 01296 */ 01297 MemberView<UnitCalculator> m_vCalculator; 01298 01299 /** 01300 * The last time that a prune was run. This value is used by the 01301 * hybrid eviction policy. 01302 * @since Coherence 3.5 01303 */ 01304 int64_t m_lLastPrune; 01305 01306 /** 01307 * For a prune cycle, this value is the average number of touches that 01308 * an entry should have. This value is used by the hybrid eviction 01309 * policy. 01310 * @since Coherence 3.5 01311 */ 01312 size32_t m_cAvgTouch; 01313 01314 /** 01315 * Allow mutable values. 01316 */ 01317 bool m_fAllowMutableValues; 01318 01319 // ----- friends -------------------------------------------------------- 01320 01321 friend class IteratorFilter; 01322 friend class KeySet; 01323 }; 01324 01325 COH_CLOSE_NAMESPACE3 01326 01327 #endif // COH_LOCAL_CACHE_HPP