Back to Qt.io
Contact Us Blog Download Qt
本页内容

QCache Class

template <typename Key, typename T> class QCache

QCache 类是一个提供缓存功能的模板类。更多内容...

头文件： #include <QCache>
CMake： find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake： QT += core

注意：该类中的所有函数均为可重入的。

公共函数

QCache(qsizetype maxCost = 100)
~QCache()
void clear()
bool contains(const Key &key) const
qsizetype count() const
bool insert(const Key &key, T *object, qsizetype cost = 1)
bool isEmpty() const
QList<Key> keys() const
qsizetype maxCost() const
T *object(const Key &key) const
bool remove(const Key &key)
void setMaxCost(qsizetype cost)
qsizetype size() const
T *take(const Key &key)
qsizetype totalCost() const
T *operator[](const Key &key) const

详细说明

QCache<Key, T> 定义了一个缓存，用于存储与类型为Key 的键相关联的类型为T 的对象。例如，以下是一个缓存的定义，该缓存存储与整数键相关联的类型为 Employee 的对象：

QCache<int, Employee> cache;

以下是将对象插入缓存的方法：

Employee *employee = new Employee;
employee->setId(37);
employee->setName("Richard Schmit");
//...
cache.insert(employee->id(), employee);

与其他基于键的数据结构（如QMap 或QHash ）相比，使用 QCache 的优势在于：QCache 会自动获取插入缓存中的对象的所有权，并在必要时删除这些对象以腾出空间容纳新对象。 将对象插入缓存时，您可以指定一个成本值，该值应与对象占用的内存量大致成正比。 当所有对象成本的总和（totalCost())）超过缓存的限制（maxCost()）时，QCache 会开始删除缓存中的对象以保持在限制之下，从最近访问次数较少的对象开始。

默认情况下，QCache 的maxCost() 值为 100。您可以在 QCache 构造函数中指定其他值：

QCache<int, MyDataStructure> cache(5000);

每次调用insert() 时，您可以将成本作为第三个参数（位于键和待插入对象的指针之后）进行指定。调用完成后，插入的对象归 QCache 所有，QCache 可能会随时将其删除以腾出空间给其他对象。

要在缓存中查找对象，请使用 `object()` 或 `operator[]()`。该函数根据键查找对象，并返回缓存对象的指针（该对象由缓存拥有）或 `nullptr`。

若要从缓存中移除特定键对应的对象，请调用remove()。这也会删除该对象。若要从缓存中移除对象而不让 QCache 删除它，请使用take()。

另请参阅 QPixmapCache 、QHash 和QMap 。

成员函数文档

[explicit noexcept] QCache::QCache(qsizetype maxCost = 100)

构建一个缓存，其内容的总成本永远不会超过maxCost 。

QCache::~QCache()

清除缓存。删除缓存中的所有对象。

[noexcept(...)] void QCache::clear()

删除缓存中的所有对象。

注意： 当std::is_nothrow_destructible_v<Node> 的值是true 时，此 函数为noexcept。

另请参阅 remove() 和take()。

[noexcept] bool QCache::contains(const Key &key) const

如果缓存中包含与键key 关联的对象，则返回true ；否则返回false 。

另请参阅 take() 和remove()。

[noexcept] qsizetype QCache::count() const

与size() 相同。

bool QCache::insert(const Key &key, T *object, qsizetype cost = 1)

将object 作为缓存项插入缓存，键为key ，关联成本为cost 。如果缓存中已存在键相同的对象，则将其移除。

调用此函数后，object 由QCache 拥有，并可能随时被删除。特别是，如果cost 大于maxCost()，该对象将立即被删除。

如果对象已被插入缓存，该函数返回true ；否则返回false 。

另请参见 take() 和remove()。

[noexcept] bool QCache::isEmpty() const

如果缓存中不包含任何对象，则返回 `true `；否则返回 `false`。

另请参阅 size()。

QList<Key> QCache::keys() const

返回缓存中键的列表。

[noexcept] qsizetype QCache::maxCost() const

返回缓存的最大允许总成本。

另请参阅 setMaxCost() 和totalCost()。

[noexcept] T *QCache::object(const Key &key) const

返回与键key 关联的对象；如果缓存中不存在该键，则返回nullptr 。

警告： 返回的对象由QCache 拥有，并可能随时被删除。

另请参阅 take() 和remove()。

[noexcept(...)] bool QCache::remove(const Key &key)

删除与键key 关联的对象。如果在缓存中找到了该对象，则返回true ；否则返回false 。

注意： 当std::is_nothrow_destructible_v<Node> 为true 时，此 函数为 noexcept。

另请参阅 take() 和clear()。

[noexcept(...)] void QCache::setMaxCost(qsizetype cost)

将缓存的最大允许总成本设置为cost 。如果当前总成本大于cost ，则会立即删除部分对象。

注意： 当std::is_nothrow_destructible_v<Node> 等于true 时，此 函数为 noexcept。

另请参阅 maxCost() 和totalCost()。

[noexcept] qsizetype QCache::size() const

返回缓存中对象的数量。

另请参阅 ` isEmpty()`。

[noexcept(...)] T *QCache::take(const Key &key)

将与键key 关联的对象从缓存中取出，但不删除该对象。返回所取出对象的指针；如果缓存中不存在该键，则返回0。

返回对象的所有权将转移给调用方。

注意： 当std::is_nothrow_destructible_v<Key> 为true 时，此 函数为 noexcept。

另请参阅 remove()。

[noexcept] qsizetype QCache::totalCost() const

返回缓存中所有对象的总成本。

该值通常小于 `maxCost()` 的返回值，但 `QCache ` 对于 Qt的隐式共享类会是个例外。如果缓存中的对象与其另一个实例共享内部数据，`QCache ` 可能会保留该对象，从而可能导致 `totalCost()` 的值大于 `maxCost()` 的返回值。

另请参阅 setMaxCost()。

[noexcept] T *QCache::operator[](const Key &key) const

返回与键key 关联的对象；如果缓存中不存在该键，则返回nullptr 。

这与object() 效果相同。

警告： 返回的对象由 `QCache ` 拥有，并可能随时被删除。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.