Long live QAIM::multiData!

Views / delegates absolutely *adore* hammering data(). A simple
QListView showing a couple of dozens entries can call data()
a hundred of times on the first show.

Back of the hand calculation,

* 2 times per visible item (sizeHint() + paint()),
* times 9 roles used by the default delegate,
* times 20 visible items

= 360 as a bare minimum, assuming the view doesn't redraw twice
accidentally. Move the mouse over the view, and that'll cause
a full update with certain styles: 360 calls to data() per update.

This has an overhead visible in profilers. The model's data()
has to re-fetch the index from its data structure and extract
the requested field every time.

Also, QVariant is used for the data interexchange,
meaning anything that won't fit in one is also a memory allocation.
This problem will likely be gone in Qt6Variant as that
will store sizeof(void*) * 3, meaning QImage/QPixmap and similar
polymorphic classes will fit in a QVariant now...

So I'm trying to to remove part of that overhead by allowing
views to request all the data they need in one go. For now,
one index a a time.

A view might also store the data returned. The idea is that
the same role on different indexes will _very likely_
return variants of the same type. So a model could move-assign
the data into the variant, avoiding the memory allocation
/deallocation for the variant's private.

This patch:

1) Introduces QModelRoleData as a holder for role+data.

2) Introduces QModelRoleDataSpan as a span over QModelRoleData.
The idea of a span type is twofold. First and foremost, we are
in no position to choose which kind of container a view should
use to store the QModelRoleData objects for a multiData() call;
a span abstracts any contiguous sequence, leaving the view free
to do whatever it wants (statically allocate, use a vector, etc.).
It also solves the problem of efficient passing the roles and
gathering the returned variants from multiData().

3) Add multiData(), which populates a span of roles for a given
model index. The main advantage here is that a model can fetch
all the needed information for a given index just once, then
iterate on the span and provide data for each requested role.
Cf. this with data(), where every call has to re-fetch
the information for the index.

A couple of models have been ported to multiData(), as well as
QStyledItemDelegate.

[ChangeLog][QtCore][QModelRoleData] New class.

[ChangeLog][QtCore][QModelRoleDataSpan] New class.

[ChangeLog][QtCore][QAbstractItemModel] Added the multiData()
function.

Change-Id: Icce0d108ad4e156c9fb05c83ce6df5f58f99f118
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>

1 files changed, 298 insertions, 0 deletions

diff --git a/src/corelib/itemmodels/qabstractitemmodel.cpp b/src/corelib/itemmodels/qabstractitemmodel.cpp
index a686e918c3..8314ea8958 100644
--- a/src/corelib/itemmodels/qabstractitemmodel.cpp
+++ b/src/corelib/itemmodels/qabstractitemmodel.cpp
@@ -1,6 +1,7 @@
 /****************************************************************************
 **
 ** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2020 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the QtCore module of the Qt Toolkit.
@@ -91,6 +92,226 @@ void QPersistentModelIndexData::destroy(QPersistentModelIndexData *data)
 }
 
 /*!
+    \class QModelRoleData
+    \inmodule QtCore
+    \since 6.0
+    \ingroup model-view
+    \brief The QModelRoleData class holds a role and the data associated to that role.
+
+    QModelRoleData objects store an item role (which is a value from the
+    Qt::ItemDataRole enumeration, or an arbitrary integer for a custom role)
+    as well as the data associated with that role.
+
+    A QModelRoleData object is typically created by views or delegates,
+    setting which role they want to fetch the data for. The object
+    is then passed to models (see QAbstractItemModel::multiData()),
+    which populate the data corresponding to the role stored. Finally,
+    the view visualizes the data retrieved from the model.
+
+    \sa {Model/View Programming}, QModelRoleDataSpan
+*/
+
+/*!
+    QModelRoleData::QModelRoleData(int role) noexcept
+
+    Constructs a QModelRoleData object for the given \a role.
+
+    \sa Qt::ItemDataRole
+*/
+
+/*!
+    int QModelRoleData::role() const noexcept
+
+    Returns the role held by this object.
+
+    \sa Qt::ItemDataRole
+*/
+
+/*!
+    const QVariant &QModelRoleData::data() const noexcept
+
+    Returns the data held by this object.
+
+    \sa setData()
+*/
+
+/*!
+    QVariant &QModelRoleData::data() noexcept
+
+    Returns the data held by this object as a modifiable reference.
+
+    \sa setData()
+*/
+
+/*!
+    template <typename T> void QModelRoleData::setData(T &&value)
+
+    Sets the data held by this object to \a value.
+    \a value must be of a datatype which can be stored in a QVariant.
+
+    \sa data(), clearData(), Q_DECLARE_METATYPE
+*/
+
+/*!
+    void QModelRoleData::clearData() noexcept
+
+    Clears the data held by this object. Note that the role is
+    unchanged; only the data is cleared.
+
+    \sa data()
+*/
+
+/*!
+    \class QModelRoleDataSpan
+    \inmodule QtCore
+    \since 6.0
+    \ingroup model-view
+    \brief The QModelRoleDataSpan class provides a span over QModelRoleData objects.
+
+    A QModelRoleDataSpan is used as an abstraction over an array of
+    QModelRoleData objects.
+
+    Like a view, QModelRoleDataSpan provides a small object (pointer
+    and size) that can be passed to functions that need to examine the
+    contents of the array. A QModelRoleDataSpan can be constructed from
+    any array-like sequence (plain arrays, QVector, std::vector,
+    QVarLengthArray, and so on). Moreover, it does not own the
+    sequence, which must therefore be kept alive longer than any
+    QModelRoleDataSpan objects referencing it.
+
+    Unlike a view, QModelRoleDataSpan is a span, so it allows for
+    modifications to the underlying elements.
+
+    QModelRoleDataSpan's main use case is making it possible
+    for a model to return the data corresponding to different roles
+    in one call.
+
+    In order to draw one element from a model, a view (through its
+    delegates) will generally request multiple roles for the same index
+    by calling \c{data()} as many times as needed:
+
+    \snippet code/src_corelib_kernel_qabstractitemmodel.cpp 13
+
+    QModelRoleDataSpan allows a view to request the same data
+    using just one function call.
+
+    This is achieved by having the view prepare a suitable array of
+    QModelRoleData objects, each initialized with the role that should
+    be fetched. The array is then wrapped in a QModelRoleDataSpan
+    object, which is then passed to a model's \c{multiData()} function.
+
+    \snippet code/src_corelib_kernel_qabstractitemmodel.cpp 14
+
+    Views are encouraged to store the array of QModelRoleData objects
+    (and, possibly, the corresponding span) and re-use it in subsequent
+    calls to the model. This allows to reduce the memory allocations
+    related with creating and returning QVariant objects.
+
+    Finally, given a QModelRoleDataSpan object, the model's
+    responsibility is to fill in the data corresponding to each role in
+    the span. How this is done depends on the concrete model class.
+    Here's a sketch of a possible implementation that iterates over the
+    span and uses \c{setData()} on each element:
+
+    \snippet code/src_corelib_kernel_qabstractitemmodel.cpp 15
+
+    \sa {Model/View Programming}, QAbstractItemModel::multiData()
+*/
+
+/*!
+    QModelRoleDataSpan::QModelRoleDataSpan() noexcept
+
+    Constructs an empty QModelRoleDataSpan. Its data() will be set to
+    \nullptr, and its length to zero.
+*/
+
+/*!
+    QModelRoleDataSpan::QModelRoleDataSpan(QModelRoleData &modelRoleData) noexcept
+
+    Constructs an QModelRoleDataSpan spanning over \a modelRoleData,
+    seen as a 1-element array.
+*/
+
+/*!
+    QModelRoleDataSpan::QModelRoleDataSpan(QModelRoleData *modelRoleData, qsizetype len)
+
+    Constructs an QModelRoleDataSpan spanning over the array beginning
+    at \a modelRoleData and with length \a len.
+
+    \note The array must be kept alive as long as this object has not
+    been destructed.
+*/
+
+/*!
+    template <typename Container> QModelRoleDataSpan::QModelRoleDataSpan(Container &c) noexcept
+
+    Constructs an QModelRoleDataSpan spanning over the container \a c,
+    which can be any contiguous container of QModelRoleData objects.
+    For instance, it can be a \c{QVector<QModelRoleData>},
+    a \c{std::array<QModelRoleData, 10>} and so on.
+
+    \note The container must be kept alive as long as this object has not
+    been destructed.
+*/
+
+/*!
+    qsizetype QModelRoleDataSpan::size() const noexcept
+
+    Returns the length of the span represented by this object.
+*/
+
+/*!
+    qsizetype QModelRoleDataSpan::length() const noexcept
+
+    Returns the length of the span represented by this object.
+*/
+
+/*!
+    QModelRoleData *QModelRoleDataSpan::data() const noexcept
+
+    Returns a pointer to the beginning of the span represented by this
+    object.
+*/
+
+/*!
+    QModelRoleData *QModelRoleDataSpan::begin() const noexcept
+
+    Returns a pointer to the beginning of the span represented by this
+    object.
+*/
+
+/*!
+    QModelRoleData *QModelRoleDataSpan::end() const noexcept
+
+    Returns a pointer to the imaginary element one past the end of the
+    span represented by this object.
+*/
+
+/*!
+    QModelRoleData &QModelRoleDataSpan::operator[](qsizetype index) const
+
+    Returns a modifiable reference to the QModelRoleData at position
+    \a index in the span.
+
+    \note \a index must be a valid index for this span (0 <= \a index < size()).
+*/
+
+/*!
+    const QVariant *QModelRoleDataSpan::dataForRole(int role) const
+
+    Returns the data associated with the first QModelRoleData in the
+    span that has its role equal to \a role. If such a QModelRoleData
+    object does not exist, the behavior is undefined.
+
+    \note Avoid calling this function from the model's side, as a
+    model cannot possibly know in advance which roles are in a given
+    QModelRoleDataSpan. This function is instead suitable for views and
+    delegates, which have control over the roles in the span.
+
+    \sa QModelRoleData::data()
+*/
+
+/*!
   \class QPersistentModelIndex
   \inmodule QtCore
   \ingroup shared
@@ -423,6 +644,20 @@ QVariant QPersistentModelIndex::data(int role) const
     return QVariant();
 }
 
+
+/*!
+    Populates the given \a roleDataSpan for the item referred to by the
+    index.
+
+    \since 6.0
+    \sa Qt::ItemDataRole, QAbstractItemModel::setData()
+*/
+void QPersistentModelIndex::multiData(QModelRoleDataSpan roleDataSpan) const
+{
+    if (d)
+        d->index.multiData(roleDataSpan);
+}
+
 /*!
     \since 4.2
 
@@ -1109,6 +1344,14 @@ void QAbstractItemModel::resetInternalData()
 */
 
 /*!
+    \fn void QModelIndex::multiData(QModelRoleDataSpan roleDataSpan) const
+    \since 6.0
+
+    Populates the given \a roleDataSpan for the item referred to by the
+    index.
+*/
+
+/*!
     \fn Qt::ItemFlags QModelIndex::flags() const
     \since 4.2
 
@@ -3401,6 +3644,61 @@ bool QAbstractItemModel::checkIndex(const QModelIndex &index, CheckIndexOptions
 }
 
 /*!
+    \since 6.0
+
+    Fills the \a roleDataSpan with the requested data for the given \a index.
+
+    The default implementation will call simply data() for each role in
+    the span. A subclass can reimplement this function to provide data
+    to views more efficiently:
+
+    \snippet code/src_corelib_kernel_qabstractitemmodel.cpp 15
+
+    In the snippet above, \c{index} is the same for the entire call.
+    This means that accessing to the necessary data structures in order
+    to retrieve the information for \c{index} can be done only once
+    (hoisting the relevant code out of the loop).
+
+    The usage of QModelRoleData::setData(), or similarly
+    QVariant::setValue(), is encouraged over constructing a QVariant
+    separately and  using a plain assignment operator; this is
+    because the former allow to re-use the memory already allocated for
+    the QVariant object stored inside a QModelRoleData, while the latter
+    always allocates the new variant and then destroys the old one.
+
+    Note that views may call multiData() with spans that have been used
+    in previous calls, and therefore may already contain some data.
+    Therefore, it is imperative that if the model cannot return the
+    data for a given role, then it must clear the data in the
+    corresponding QModelRoleData object. This can be done by calling
+    QModelRoleData::clearData(), or similarly by setting a default
+    constructed QVariant, and so on. Failure to clear the data will
+    result in the view believing that the "old" data is meant to be
+    used for the corresponding role.
+
+    Finally, in order to avoid code duplication, a subclass may also
+    decide to reimplement data() in terms of multiData(), by supplying
+    a span of just one element:
+
+    \snippet code/src_corelib_kernel_qabstractitemmodel.cpp 16
+
+    \note Models are not allowed to modify the roles in the span, or
+    to rearrange the span elements. Doing so results in undefined
+    behavior.
+
+    \note It is illegal to pass an invalid model index to this function.
+
+    \sa QModelRoleDataSpan, data()
+*/
+void QAbstractItemModel::multiData(const QModelIndex &index, QModelRoleDataSpan roleDataSpan) const
+{
+    Q_ASSERT(checkIndex(index, CheckIndexOption::IndexIsValid));
+
+    for (QModelRoleData &d : roleDataSpan)
+        d.setData(data(index, d.role()));
+}
+
+/*!
     \class QAbstractTableModel
     \inmodule QtCore
     \brief The QAbstractTableModel class provides an abstract model that can be