1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \class QCache

    44     \brief The QCache class is a template class that provides a cache.

    45 

    46     \ingroup tools

    47     \ingroup shared

    48 

    49     \reentrant

    50 

    51     QCache\<Key, T\> defines a cache that stores objects of type T

    52     associated with keys of type Key. For example, here's the

    53     definition of a cache that stores objects of type Employee

    54     associated with an integer key:

    55 

    56     \snippet doc/src/snippets/code/doc_src_qcache.qdoc 0

    57 

    58     Here's how to insert an object in the cache:

    59 

    60     \snippet doc/src/snippets/code/doc_src_qcache.qdoc 1

    61 

    62     The advantage of using QCache over some other key-based data

    63     structure (such as QMap or QHash) is that QCache automatically

    64     takes ownership of the objects that are inserted into the cache and

    65     deletes them to make room for new objects, if necessary. When

    66     inserting an object into the cache, you can specify a \e{cost},

    67     which should bear some approximate relationship to the amount of

    68     memory taken by the object. When the sum of all objects' costs

    69     (totalCost()) exceeds the cache's limit (maxCost()), QCache starts

    70     deleting objects in the cache to keep under the limit, starting with

    71     less recently accessed objects.

    72 

    73     By default, QCache's maxCost() is 100. You can specify a

    74     different value in the QCache constructor:

    75 

    76     \snippet doc/src/snippets/code/doc_src_qcache.qdoc 2

    77 

    78     Each time you call insert(), you can specify a cost as third

    79     argument (after the key and a pointer to the object to insert).

    80     After the call, the inserted object is owned by the QCache, which

    81     may delete it at any time to make room for other objects.

    82 

    83     To look up objects in the cache, use object() or

    84     operator[](). This function looks up an object by its key, and

    85     returns either a pointer to the cached object (which is owned by

    86     the cache) or 0.

    87 

    88     If you want to remove an object from the cache for a particular key,

    89     call remove(). This will also delete the object. If you want to

    90     remove an object from the cache without the QCache deleting it, use

    91     take().

    92 

    93     \sa QPixmapCache, QHash, QMap

    94 */

    95 

    96 /*! \fn QCache::QCache(int maxCost = 100)

    97 

    98     Constructs a cache whose contents will never have a total cost

    99     greater than \a maxCost.

   100 */

   101 

   102 /*! \fn QCache::~QCache()

   103 

   104     Destroys the cache. Deletes all the objects in the cache.

   105 */

   106 

   107 /*! \fn int QCache::maxCost() const

   108 

   109     Returns the maximum allowed total cost of the cache.

   110 

   111     \sa setMaxCost(), totalCost()

   112 */

   113 

   114 /*! \fn void QCache::setMaxCost(int cost)

   115 

   116     Sets the maximum allowed total cost of the cache to \a cost. If

   117     the current total cost is greater than \a cost, some objects are

   118     deleted immediately.

   119 

   120     \sa maxCost(), totalCost()

   121 */

   122 

   123 /*! \fn int QCache::totalCost() const

   124 

   125     Returns the total cost of the objects in the cache.

   126 

   127     This value is normally below maxCost(), but QCache makes an

   128     exception for Qt's \l{implicitly shared} classes. If a cached

   129     object shares its internal data with another instance, QCache may

   130     keep the object lying around, possibly contributing to making

   131     totalCost() larger than maxCost().

   132 

   133     \sa setMaxCost()

   134 */

   135 

   136 /*! \fn int QCache::size() const

   137 

   138     Returns the number of objects in the cache.

   139 

   140     \sa isEmpty()

   141 */

   142 

   143 /*! \fn int QCache::count() const

   144 

   145     Same as size().

   146 */

   147 

   148 /*! \fn bool QCache::isEmpty() const

   149 

   150     Returns true if the cache contains no objects; otherwise

   151     returns false.

   152 

   153     \sa size()

   154 */

   155 

   156 /*! \fn QList<Key> QCache::keys() const

   157 

   158     Returns a list of the keys in the cache.

   159 */

   160 

   161 /*! \fn void QCache::clear();

   162 

   163     Deletes all the objects in the cache.

   164 

   165     \sa remove(), take()

   166 */

   167 

   168 

   169 /*! \fn bool QCache::insert(const Key &key, T *object, int cost = 1)

   170 

   171     Inserts \a object into the cache with key \a key and

   172     associated cost \a cost. Any object with the same key already in

   173     the cache will be removed.

   174 

   175     After this call, \a object is owned by the QCache and may be

   176     deleted at any time. In particular, if \a cost is greater than

   177     maxCost(), the object will be deleted immediately.

   178 

   179     The function returns true if the object was inserted into the

   180     cache; otherwise it returns false.

   181 

   182     \sa take(), remove()

   183 */

   184 

   185 /*! \fn T *QCache::object(const Key &key) const

   186 

   187     Returns the object associated with key \a key, or 0 if the key does

   188     not exist in the cache.

   189 

   190     \warning The returned object is owned by QCache and may be

   191     deleted at any time.

   192 

   193     \sa take(), remove()

   194 */

   195 

   196 /*! \fn bool QCache::contains(const Key &key) const

   197 

   198     Returns true if the cache contains an object associated with key \a

   199     key; otherwise returns false.

   200 

   201     \sa take(), remove()

   202 */

   203 

   204 /*! \fn T *QCache::operator[](const Key &key) const

   205 

   206     Returns the object associated with key \a key, or 0 if the key does

   207     not exist in the cache.

   208 

   209     This is the same as object().

   210 

   211     \warning The returned object is owned by QCache and may be

   212     deleted at any time.

   213 */

   214 

   215 /*! \fn bool QCache::remove(const Key &key)

   216 

   217     Deletes the object associated with key \a key. Returns true if the

   218     object was found in the cache; otherwise returns false.

   219 

   220     \sa take(), clear()

   221 */

   222 

   223 /*! \fn T *QCache::take(const Key &key)

   224 

   225     Takes the object associated with key \a key out of the cache

   226     without deleting it. Returns a pointer to the object taken out, or

   227     0 if the key does not exist in the cache.

   228 

   229     The ownership of the returned object is passed to the caller.

   230 

   231     \sa remove()

   232 */

   233 

   234 /*!

   235     \fn QCache::QCache(int maxCost, int dummy)

   236 

   237     Use QCache(int) instead.

   238 */

   239 

   240 /*!

   241     \fn T *QCache::find(const Key &key) const

   242 

   243     Use object() instead.

   244 */