Oracle Coherence for C++ API
Release 3.6.0.0
E15728-01

- Main Page
- Namespaces
- Classes
- Files

# coherence/util/WeakHashMap.hpp

    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 &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     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 &lt; n
    00134                 * @param flLoadFactor     the acceptable load factor before
    00135                 *                         resizing occurs, 0 &lt; 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 &lt; 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

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.