doc/src/examples/contiguouscache.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example tools/contiguouscache
  30     \title Contiguous Cache Example
  31
  32     \brief The Contiguous Cache example shows how to use QContiguousCache to manage memory usage for
  33     very large models.
  34
  35     In some environments memory is limited and, even when it
  36     isn't, users still dislike an application using excessive memory.
  37     Using QContiguousCache to manage a list, rather than loading
  38     the entire list into memory, allows the application to limit the amount
  39     of memory it uses, regardless of the size of the data set it accesses
  40
  41     The simplest way to use QContiguousCache is to cache as items are requested. When
  42     a view requests an item at row N it is also likely to ask for items at rows near
  43     to N.
  44
  45     \snippet examples/tools/contiguouscache/randomlistmodel.cpp 0
  46
  47     After getting the row, the class determines if the row is in the bounds
  48     of the contiguous cache's current range.  It would have been equally valid to
  49     simply have the following code instead.
  50
  51     \code
  52     while (row > m_rows.lastIndex())
  53         m_rows.append(fetchWord(m_rows.lastIndex()+1);
  54     while (row < m_rows.firstIndex())
  55         m_rows.prepend(fetchWord(m_rows.firstIndex()-1);
  56     \endcode
  57
  58     However a list will often jump rows if the scroll bar is used directly, resulting in
  59     the code above causing every row between the old and new rows to be fetched.
  60
  61     Using QContiguousCache::lastIndex() and QContiguousCache::firstIndex() allows
  62     the example to determine what part of the list the cache is currently caching.
  63     These values don't represent the indexes into the cache's own memory, but rather
  64     a virtual infinite array that the cache represents.
  65
  66     By using QContiguousCache::append() and QContiguousCache::prepend() the code ensures
  67     that items that may be still on the screen are not lost when the requested row
  68     has not moved far from the current cache range.  QContiguousCache::insert() can
  69     potentially remove more than one item from the cache as QContiguousCache does not
  70     allow for gaps.  If your cache needs to quickly jump back and forth between
  71     rows with significant gaps between them consider using QCache instead.
  72
  73     And thats it.  A perfectly reasonable cache, using minimal memory for a very large
  74     list.  In this case the accessor for getting the words into the cache
  75     generates random information rather than fixed information.  This allows you
  76     to see how the cache range is kept for a local number of rows when running the
  77     example.
  78
  79     \snippet examples/tools/contiguouscache/randomlistmodel.cpp 1
  80
  81     It is also worth considering pre-fetching items into the cache outside of the
  82     application's paint routine.  This can be done either with a separate thread
  83     or using a QTimer to incrementally expand the range of the cache prior to
  84     rows being requested out of the current cache range.
  85 */