source: branches/4.5.1/doc/src/qcache.qdoc@ 664

Last change on this file since 664 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.
File size: 7.4 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information (qt-info@nokia.com)
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at qt-sales@nokia.com.
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 \mainclass
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*/
Note: See TracBrowser for help on using the repository browser.