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