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