src/corelib/tools/qcache.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \class QCache
  30     \brief The QCache class is a template class that provides a cache.
  31
  32     \ingroup tools
  33     \ingroup shared
  34
  35     \reentrant
  36
  37     QCache\<Key, T\> defines a cache that stores objects of type T
  38     associated with keys of type Key. For example, here's the
  39     definition of a cache that stores objects of type Employee
  40     associated with an integer key:
  41
  42     \snippet code/doc_src_qcache.cpp 0
  43
  44     Here's how to insert an object in the cache:
  45
  46     \snippet code/doc_src_qcache.cpp 1
  47
  48     The advantage of using QCache over some other key-based data
  49     structure (such as QMap or QHash) is that QCache automatically
  50     takes ownership of the objects that are inserted into the cache and
  51     deletes them to make room for new objects, if necessary. When
  52     inserting an object into the cache, you can specify a \e{cost},
  53     which should bear some approximate relationship to the amount of
  54     memory taken by the object. When the sum of all objects' costs
  55     (totalCost()) exceeds the cache's limit (maxCost()), QCache starts
  56     deleting objects in the cache to keep under the limit, starting with
  57     less recently accessed objects.
  58
  59     By default, QCache's maxCost() is 100. You can specify a
  60     different value in the QCache constructor:
  61
  62     \snippet code/doc_src_qcache.cpp 2
  63
  64     Each time you call insert(), you can specify a cost as third
  65     argument (after the key and a pointer to the object to insert).
  66     After the call, the inserted object is owned by the QCache, which
  67     may delete it at any time to make room for other objects.
  68
  69     To look up objects in the cache, use object() or
  70     operator[](). This function looks up an object by its key, and
  71     returns either a pointer to the cached object (which is owned by
  72     the cache) or 0.
  73
  74     If you want to remove an object from the cache for a particular key,
  75     call remove(). This will also delete the object. If you want to
  76     remove an object from the cache without the QCache deleting it, use
  77     take().
  78
  79     \sa QPixmapCache, QHash, QMap
  80 */
  81
  82 /*! \fn QCache::QCache(int maxCost = 100)
  83
  84     Constructs a cache whose contents will never have a total cost
  85     greater than \a maxCost.
  86 */
  87
  88 /*! \fn QCache::~QCache()
  89
  90     Destroys the cache. Deletes all the objects in the cache.
  91 */
  92
  93 /*! \fn int QCache::maxCost() const
  94
  95     Returns the maximum allowed total cost of the cache.
  96
  97     \sa setMaxCost(), totalCost()
  98 */
  99
 100 /*! \fn void QCache::setMaxCost(int cost)
 101
 102     Sets the maximum allowed total cost of the cache to \a cost. If
 103     the current total cost is greater than \a cost, some objects are
 104     deleted immediately.
 105
 106     \sa maxCost(), totalCost()
 107 */
 108
 109 /*! \fn int QCache::totalCost() const
 110
 111     Returns the total cost of the objects in the cache.
 112
 113     This value is normally below maxCost(), but QCache makes an
 114     exception for Qt's \l{implicitly shared} classes. If a cached
 115     object shares its internal data with another instance, QCache may
 116     keep the object lying around, possibly contributing to making
 117     totalCost() larger than maxCost().
 118
 119     \sa setMaxCost()
 120 */
 121
 122 /*! \fn int QCache::size() const
 123
 124     Returns the number of objects in the cache.
 125
 126     \sa isEmpty()
 127 */
 128
 129 /*! \fn int QCache::count() const
 130
 131     Same as size().
 132 */
 133
 134 /*! \fn bool QCache::isEmpty() const
 135
 136     Returns true if the cache contains no objects; otherwise
 137     returns false.
 138
 139     \sa size()
 140 */
 141
 142 /*! \fn QList<Key> QCache::keys() const
 143
 144     Returns a list of the keys in the cache.
 145 */
 146
 147 /*! \fn void QCache::clear();
 148
 149     Deletes all the objects in the cache.
 150
 151     \sa remove(), take()
 152 */
 153
 154
 155 /*! \fn bool QCache::insert(const Key &key, T *object, int cost = 1)
 156
 157     Inserts \a object into the cache with key \a key and
 158     associated cost \a cost. Any object with the same key already in
 159     the cache will be removed.
 160
 161     After this call, \a object is owned by the QCache and may be
 162     deleted at any time. In particular, if \a cost is greater than
 163     maxCost(), the object will be deleted immediately.
 164
 165     The function returns true if the object was inserted into the
 166     cache; otherwise it returns false.
 167
 168     \sa take(), remove()
 169 */
 170
 171 /*! \fn T *QCache::object(const Key &key) const
 172
 173     Returns the object associated with key \a key, or 0 if the key does
 174     not exist in the cache.
 175
 176     \warning The returned object is owned by QCache and may be
 177     deleted at any time.
 178
 179     \sa take(), remove()
 180 */
 181
 182 /*! \fn bool QCache::contains(const Key &key) const
 183
 184     Returns true if the cache contains an object associated with key \a
 185     key; otherwise returns false.
 186
 187     \sa take(), remove()
 188 */
 189
 190 /*! \fn T *QCache::operator[](const Key &key) const
 191
 192     Returns the object associated with key \a key, or 0 if the key does
 193     not exist in the cache.
 194
 195     This is the same as object().
 196
 197     \warning The returned object is owned by QCache and may be
 198     deleted at any time.
 199 */
 200
 201 /*! \fn bool QCache::remove(const Key &key)
 202
 203     Deletes the object associated with key \a key. Returns true if the
 204     object was found in the cache; otherwise returns false.
 205
 206     \sa take(), clear()
 207 */
 208
 209 /*! \fn T *QCache::take(const Key &key)
 210
 211     Takes the object associated with key \a key out of the cache
 212     without deleting it. Returns a pointer to the object taken out, or
 213     0 if the key does not exist in the cache.
 214
 215     The ownership of the returned object is passed to the caller.
 216
 217     \sa remove()
 218 */