doc/src/examples/contiguouscache.qdoc

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