Oracle Coherence for C++ API
Release 3.7.0.0

E18684-01

coherence/util/WeakHashMap.hpp

00001 /*
00002 * WeakHashMap.hpp
00003 *
00004 * Copyright (c) 2000, 2011, 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 &lt; n
00055         * @param flLoadFactor     the acceptable load factor before resizing
00056         *                         occurs, 0 &lt; 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 &lt; 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 &lt; n
00140                 * @param flLoadFactor     the acceptable load factor before
00141                 *                         resizing occurs, 0 &lt; 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 &lt; 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
Copyright © 2000, 2011, Oracle and/or its affiliates. All rights reserved.