00001 /* 00002 * WeakHashMap.hpp 00003 * 00004 * Copyright (c) 2000, 2010, 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 protected: 00098 /** 00099 * Shrink the specified bucket. 00100 * 00101 * @param iBucket the bucket to shrink 00102 * @param cEntries the maximum number of entries to shrink by 00103 * 00104 * @return the number of entries removed 00105 */ 00106 virtual size32_t shrink(size32_t iBucket, size32_t cEntries); 00107 00108 00109 // ----- inner class: Entry --------------------------------------------- 00110 00111 protected: 00112 /** 00113 * A map entry (key-value pair). The <tt>Map.entrySet</tt> method 00114 * returns a collection-view of the map, whose elements are of this 00115 * class. 00116 * 00117 * The stored key is always a WeakReference to the user supplied key. 00118 */ 00119 class COH_EXPORT Entry 00120 : public cloneable_spec<Entry, 00121 extends<SafeHashMap::Entry> > 00122 { 00123 friend class factory<Entry>; 00124 00125 // ----- constructor ---------------------------------------- 00126 00127 protected: 00128 /** 00129 * Construct a thread-safe weak hash map using the specified 00130 * settings. 00131 * 00132 * @param cInitialBuckets the initial number of hash buckets, 00133 * 0 < n 00134 * @param flLoadFactor the acceptable load factor before 00135 * resizing occurs, 0 < n, such 00136 * that a load factor of 1.0 causes 00137 * resizing when the number of entries 00138 * exceeds the number of buckets 00139 * @param flGrowthRate the rate of bucket growth when a 00140 * resize occurs, 0 < n, such that 00141 * a growth rate of 1.0 will double 00142 * the number of buckets: 00143 * bucketcount = 00144 * bucketcount * (1 + growthrate) 00145 */ 00146 Entry(Object::View vKey, Object::Holder ohValue, 00147 size32_t nHash); 00148 00149 /** 00150 * Copy constructor 00151 */ 00152 Entry(const Entry& that); 00153 00154 /** 00155 * Copy an Entry. 00156 * 00157 * @param vThat the entry to copy 00158 */ 00159 Entry(Entry::View vThat); 00160 00161 // ----- WeakHashMap::Entry interface ----------------------- 00162 00163 public: 00164 /** 00165 * Return true the entry references a key which is still 00166 * valid, i.e. has not been reclaimed. 00167 * 00168 * @return true if the key is still valid 00169 */ 00170 virtual bool isValid() const; 00171 00172 // ----- SafeHashMap::Entry interface ----------------------- 00173 00174 protected: 00175 /** 00176 * {@inheritDoc} 00177 */ 00178 virtual bool isKeyEqual(Object::View vKey) const; 00179 00180 // ----- Map::Entry interface ------------------------------- 00181 00182 public: 00183 /** 00184 * {@inheritDoc} 00185 */ 00186 virtual Object::View getKey() const; 00187 00188 // ----- friends -------------------------------------------- 00189 00190 friend class WeakHashMap; 00191 }; 00192 }; 00193 00194 COH_CLOSE_NAMESPACE2 00195 00196 #endif // COH_WEAK_HASH_MAP_HPP