00001 /* 00002 * WeakHashMap.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_WEAK_HASH_MAP_HPP 00017 #define COH_WEAK_HASH_MAP_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/util/SafeHashMap.hpp" 00022 00023 COH_OPEN_NAMESPACE2(coherence,util) 00024 00025 00026 /** 00027 * WeakHashMap is a HashMap implementation based on weak keys. That is the 00028 * use an object as a key in the map will not prevent it from being destroyed 00029 * if all other non-weak references to it are released. 00030 * 00031 * The time at which the entry associated with the weak key is cleaned up is 00032 * not guaranteed, it may live in the map for some time. While it is not safe 00033 * to assume that the map will shrink to its absolute minimum at any point, it 00034 * is safe to assume that given constant random key insertions the size of the 00035 * map will initially grow and then stabilize as the keys are reclaimed. 00036 * 00037 * Note: Iterating the entries may yield entries with reclaimed (NULL) keys. 00038 * 00039 * @author mf 2008.05.27 00040 */ 00041 class COH_EXPORT WeakHashMap 00042 : public cloneable_spec<WeakHashMap, 00043 extends<SafeHashMap> > 00044 { 00045 friend class factory<WeakHashMap>; 00046 00047 // ----- constructors --------------------------------------------------- 00048 00049 protected: 00050 /** 00051 * Construct a thread-safe weak hash map using the specified settings. 00052 * 00053 * @param cInitialBuckets the initial number of hash buckets, 00054 * 0 < n 00055 * @param flLoadFactor the acceptable load factor before resizing 00056 * occurs, 0 < n, such that a load factor 00057 * of 1.0 causes resizing when the number of 00058 * entries exceeds the number of buckets 00059 * @param flGrowthRate the rate of bucket growth when a resize 00060 * occurs, 0 < n, such that a growth rate 00061 * of 1.0 will double the number of buckets: 00062 * bucketcount = bucketcount * (1 + growthrate) 00063 */ 00064 WeakHashMap(size32_t cInitialBuckets = 17, 00065 float32_t flLoadFactor = 1.0F, 00066 float32_t flGrowthRate = 3.0F); 00067 00068 /** 00069 * Copy constructor. 00070 */ 00071 WeakHashMap(const WeakHashMap& that); 00072 00073 00074 // ----- SafeHashMap interface ------------------------------------------ 00075 00076 protected: 00077 /** 00078 * {@inheritDoc} 00079 */ 00080 virtual SafeHashMap::Entry::Handle instantiateEntry(Object::View vKey, 00081 Object::Holder ohValue, size32_t nHash); 00082 00083 /** 00084 * {@inheritDoc} 00085 */ 00086 virtual SafeHashMap::Entry::Handle instantiateEntry( 00087 SafeHashMap::Entry::View vThat); 00088 00089 /** 00090 * {@inheritDoc} 00091 */ 00092 virtual void grow(); 00093 00094 00095 // ----- WeakHashMap interface ------------------------------------------ 00096 00097 public: 00098 /** 00099 * Cleanup any "garbage" entries in the map. 00100 */ 00101 virtual void compact(); 00102 00103 protected: 00104 /** 00105 * Shrink the specified bucket. 00106 * 00107 * @param iBucket the bucket to shrink 00108 * @param cEntries the maximum number of entries to shrink by 00109 * 00110 * @return the number of entries removed 00111 */ 00112 virtual size32_t shrink(size32_t iBucket, size32_t cEntries); 00113 00114 00115 // ----- inner class: Entry --------------------------------------------- 00116 00117 protected: 00118 /** 00119 * A map entry (key-value pair). The <tt>Map.entrySet</tt> method 00120 * returns a collection-view of the map, whose elements are of this 00121 * class. 00122 * 00123 * The stored key is always a WeakReference to the user supplied key. 00124 */ 00125 class COH_EXPORT Entry 00126 : public cloneable_spec<Entry, 00127 extends<SafeHashMap::Entry> > 00128 { 00129 friend class factory<Entry>; 00130 00131 // ----- constructor ---------------------------------------- 00132 00133 protected: 00134 /** 00135 * Construct a thread-safe weak hash map using the specified 00136 * settings. 00137 * 00138 * @param cInitialBuckets the initial number of hash buckets, 00139 * 0 < n 00140 * @param flLoadFactor the acceptable load factor before 00141 * resizing occurs, 0 < n, such 00142 * that a load factor of 1.0 causes 00143 * resizing when the number of entries 00144 * exceeds the number of buckets 00145 * @param flGrowthRate the rate of bucket growth when a 00146 * resize occurs, 0 < n, such that 00147 * a growth rate of 1.0 will double 00148 * the number of buckets: 00149 * bucketcount = 00150 * bucketcount * (1 + growthrate) 00151 */ 00152 Entry(Object::View vKey, Object::Holder ohValue, 00153 size32_t nHash); 00154 00155 /** 00156 * Copy constructor 00157 */ 00158 Entry(const Entry& that); 00159 00160 /** 00161 * Copy an Entry. 00162 * 00163 * @param vThat the entry to copy 00164 */ 00165 Entry(Entry::View vThat); 00166 00167 // ----- WeakHashMap::Entry interface ----------------------- 00168 00169 public: 00170 /** 00171 * Return true the entry references a key which is still 00172 * valid, i.e. has not been reclaimed. 00173 * 00174 * @return true if the key is still valid 00175 */ 00176 virtual bool isValid() const; 00177 00178 // ----- SafeHashMap::Entry interface ----------------------- 00179 00180 protected: 00181 /** 00182 * {@inheritDoc} 00183 */ 00184 virtual bool isKeyEqual(Object::View vKey) const; 00185 00186 // ----- Map::Entry interface ------------------------------- 00187 00188 public: 00189 /** 00190 * {@inheritDoc} 00191 */ 00192 virtual Object::View getKey() const; 00193 00194 // ----- friends -------------------------------------------- 00195 00196 friend class WeakHashMap; 00197 }; 00198 }; 00199 00200 COH_CLOSE_NAMESPACE2 00201 00202 #endif // COH_WEAK_HASH_MAP_HPP