Oracle Coherence for C++ API
Release 3.7.0.0

E18684-01

coherence/util/LiteSet.hpp

00001 /*
00002 * LiteSet.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_LITE_SET_HPP
00017 #define COH_LITE_SET_HPP
00018 
00019 #include "coherence/lang.ns"
00020 
00021 #include "coherence/util/AbstractSet.hpp"
00022 #include "coherence/util/Enumeration.hpp"
00023 #include "coherence/util/Iterator.hpp"
00024 
00025 COH_OPEN_NAMESPACE2(coherence,util)
00026 
00027 
00028 /**
00029 * An implementation of coherence::util::Set that is optimal (in terms of both
00030 * size and speed) for very small sets of data but still works excellently
00031 * with large sets of data.  This implementation is not thread-safe.
00032 * <p>
00033 * The LiteSet implementation switches at runtime between several different
00034 * sub-implementations for storing the set of objects, described here:
00035 * <p>
00036 * <ol>
00037 * <li>"empty set" - a set that contains no data;
00038 * <li>"single entry" - a reference directly to an item is used to represent
00039 *     a set with exactly one item in it;
00040 * <li>"ObjectArray" - a reference is held to an array of Objects that store
00041 *     the contents of the Set; the item limit for this implementation is
00042 *     determined by the threshold constant;
00043 * <li>"delegation" - for more than threshold items, a set is created to
00044 *     delegate the set management to; sub-classes can override the default
00045 *     delegation class (HashSet) by overriding the factory method
00046 *     #instantiateSet().
00047 * </ol>
00048 * <p>
00049 * The LiteSet implementation supports the NULL value.
00050 *
00051 * @author cp/lh 10/18/2010
00052 */
00053 class COH_EXPORT LiteSet
00054     : public cloneable_spec<LiteSet,
00055         extends<AbstractSet> >
00056     {
00057     friend class factory<LiteSet>;
00058 
00059     // ----- constructors ---------------------------------------------------
00060 
00061     public:
00062         /**
00063         * Construct a LiteSet
00064         */
00065         LiteSet();
00066 
00067         /**
00068         * Construct a LiteSet containing the elements of the passed Collection.
00069         *
00070         * @param vCollection  a Collection
00071         */
00072         LiteSet(Collection::View vCollection);
00073 
00074         /*
00075         * Copy constructor
00076         *
00077         * @param that  the LiteSet instance to copy from
00078         */
00079         LiteSet(const LiteSet& that);
00080 
00081 
00082     // ----- Set interface --------------------------------------------------
00083 
00084     public:
00085         /**
00086         * {@inheritDoc}
00087         */
00088         virtual bool isEmpty() const;
00089 
00090         /**
00091         * {@inheritDoc}
00092         */
00093         virtual size32_t size() const;
00094 
00095         /**
00096         * {@inheritDoc}
00097         */
00098         virtual bool contains(Object::View v) const;
00099 
00100         /**
00101         * {@inheritDoc}
00102         */
00103         virtual Iterator::Handle iterator() const;
00104 
00105         /**
00106         * {@inheritDoc}
00107         */
00108         virtual Muterator::Handle iterator();
00109 
00110         /**
00111         * {@inheritDoc}
00112         */
00113         ObjectArray::Handle toArray(ObjectArray::Handle haDest = NULL) const;
00114 
00115         /**
00116         * {@inheritDoc}
00117         */
00118         bool add(Object::Holder oh);
00119 
00120         /**
00121         * {@inheritDoc}
00122         */
00123         bool remove(Object::View v);
00124 
00125         /**
00126         * {@inheritDoc}
00127         */
00128         virtual bool containsAll(Collection::View vCollection) const;
00129 
00130         /**
00131         * {@inheritDoc}
00132         */
00133         virtual bool addAll(Collection::View vCollection);
00134 
00135         /**
00136         * {@inheritDoc}
00137         */
00138         virtual bool retainAll(Collection::View vCollection);
00139 
00140         /**
00141         * {@inheritDoc}
00142         */
00143         virtual bool removeAll(Collection::View vCollection);
00144 
00145         /**
00146         * {@inheritDoc}
00147         */
00148         virtual void clear();
00149 
00150 
00151     // ----- internal methods -----------------------------------------------
00152 
00153     protected:
00154         /**
00155         * (Factory pattern) Instantiate a Set object to store items in once
00156         * the "lite" threshold has been exceeded. This method permits
00157         * inheriting classes to easily override the choice of the Set object.
00158         *
00159         * @return an instance of Set
00160         */
00161         Set::Handle instantiateSet();
00162 
00163         /**
00164         * (Factory pattern) Instantiate a Set object to store items in once
00165         * the "lite" threshold has been exceeded. This method permits
00166         * inheriting classes to easily override the choice of the Set object.
00167         *
00168         * @return an instance of Set
00169         */
00170         Set::View instantiateSet() const;
00171 
00172         /**
00173         * Initialize the contents of this Set from the passed array <tt>ao</tt>
00174         * containing <tt>c</tt> values.
00175         *
00176         * @param va  the array that contains the values to place in this Set
00177         * @param c   the number of values that will be placed into this Set
00178         */
00179         void initFromArray(ObjectArray::View va, size32_t c);
00180 
00181         /**
00182         * After a mutation operation has reduced the size of an underlying
00183         * Set, check if the delegation model should be replaced with a more
00184         * size-efficient storage approach, and switch accordingly.
00185         */
00186         void checkShrinkFromOther();
00187 
00188     private:
00189         /**
00190         * Scan up to the first <tt>c</tt> elements of the passed array
00191         * <tt>ao</tt> looking for the specified Object <tt>o</tt>. If it is
00192         * found, return its position <tt>i</tt> in the array such that
00193         * <tt>(0 &lt;= i &lt; c)</tt>. If it is not found, return <tt>-1</tt>.
00194         *
00195         * @param va  the array of objects to search
00196         * @param c   the number of elements in the array to search
00197         * @param v   the object to look for
00198         *
00199         * @return the index of the object, if found; otherwise -1
00200         */
00201         size32_t indexOf(ObjectArray::View va, size32_t c, Object::View v) const;
00202 
00203 
00204     // ----- constants ------------------------------------------------------
00205 
00206     private:
00207         /**
00208         * The default point above which the LiteSet delegates to another set
00209         * implementation.
00210         */
00211         static const size32_t threshold = 8;
00212 
00213         /**
00214         * Implementation:  Empty set.
00215         */
00216         static const size32_t i_empty = 0;
00217 
00218         /**
00219         * Implementation:  Single-item set.
00220         */
00221         static const size32_t i_single = 1;
00222 
00223         /**
00224         * Implementation:  Array set of 1 item.
00225         */
00226         static const size32_t i_array_1 = 2;
00227 
00228         /**
00229         * Implementation:  Array set of 2 items.
00230         */
00231         static const size32_t i_array_2 = 3;
00232 
00233         /**
00234         * Implementation:  Array set of 3 items.
00235         */
00236         static const size32_t i_array_3 = 4;
00237 
00238         /**
00239         * Implementation:  Array set of 4 items.
00240         */
00241         static const size32_t i_array_4 = 5;
00242 
00243         /**
00244         * Implementation:  Array set of 5 items.
00245         */
00246         static const size32_t i_array_5 = 6;
00247 
00248         /**
00249         * Implementation:  Array set of 6 items.
00250         */
00251         static const size32_t i_array_6 = 7;
00252 
00253         /**
00254         * Implementation:  Array set of 7 items.
00255         */
00256         static const size32_t i_array_7 = 8;
00257 
00258         /**
00259         * Implementation:  Array set of 8 items.
00260         */
00261         static const size32_t i_array_8 = 9;
00262 
00263         /**
00264         * Implementation:  Delegation.
00265         */
00266         static const size32_t i_other = 10;
00267 
00268 
00269     // ----- data members ---------------------------------------------------
00270 
00271     private:
00272         /**
00273         * Implementation, one of i_empty, i_single, i_array_* or i_other.
00274         */
00275         octet_t m_nImpl;
00276 
00277         /**
00278         * The set contents, based on the implementation being used.
00279         */
00280         MemberHolder<Object> m_hContents;
00281     };
00282 
00283 COH_CLOSE_NAMESPACE2
00284 
00285 #endif // COH_LITE_SET_HPP
Copyright © 2000, 2011, Oracle and/or its affiliates. All rights reserved.