| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \example tools/contiguouscache |
| \title Contiguous Cache Example |
| |
| \brief The Contiguous Cache example shows how to use QContiguousCache to manage memory usage for |
| very large models. In some environments memory is limited and, even when it |
| isn't, users still dislike an application using excessive memory. |
| Using QContiguousCache to manage a list, rather than loading |
| the entire list into memory, allows the application to limit the amount |
| of memory it uses, regardless of the size of the data set it accesses. |
| |
| The simplest way to use QContiguousCache is to cache as items are requested. When |
| a view requests an item at row N it is also likely to ask for items at rows near |
| to N. |
| |
| \snippet tools/contiguouscache/randomlistmodel.cpp 0 |
| |
| After getting the row, the class determines if the row is in the bounds |
| of the contiguous cache's current range. It would have been equally valid to |
| simply have the following code instead. |
| |
| \code |
| while (row > m_rows.lastIndex()) |
| m_rows.append(fetchWord(m_rows.lastIndex()+1); |
| while (row < m_rows.firstIndex()) |
| m_rows.prepend(fetchWord(m_rows.firstIndex()-1); |
| \endcode |
| |
| However a list will often jump rows if the scroll bar is used directly, resulting in |
| the code above causing every row between the old and new rows to be fetched. |
| |
| Using QContiguousCache::lastIndex() and QContiguousCache::firstIndex() allows |
| the example to determine what part of the list the cache is currently caching. |
| These values don't represent the indexes into the cache's own memory, but rather |
| a virtual infinite array that the cache represents. |
| |
| By using QContiguousCache::append() and QContiguousCache::prepend() the code ensures |
| that items that may be still on the screen are not lost when the requested row |
| has not moved far from the current cache range. QContiguousCache::insert() can |
| potentially remove more than one item from the cache as QContiguousCache does not |
| allow for gaps. If your cache needs to quickly jump back and forth between |
| rows with significant gaps between them consider using QCache instead. |
| |
| And thats it. A perfectly reasonable cache, using minimal memory for a very large |
| list. In this case the accessor for getting the words into the cache |
| generates random information rather than fixed information. This allows you |
| to see how the cache range is kept for a local number of rows when running the |
| example. |
| |
| \snippet tools/contiguouscache/randomlistmodel.cpp 1 |
| |
| It is also worth considering pre-fetching items into the cache outside of the |
| application's paint routine. This can be done either with a separate thread |
| or using a QTimer to incrementally expand the range of the cache prior to |
| rows being requested out of the current cache range. |
| */ |