From 71122209f4590a3d760f56fc8d013ef4d0b95719 Mon Sep 17 00:00:00 2001 From: Mitch Curtis Date: Tue, 18 Jul 2023 14:18:39 +0800 Subject: [PATCH] Doc: state that models are not thread-safe Fixes: QTBUG-107598 Pick-to: 6.5 6.2 5.15 Change-Id: I0e7ea8d4b2094d92b3cad5eec5b30e6e3ac64018 Reviewed-by: Thiago Macieira (cherry picked from commit ccda3362464bfaff999b739aa81925c7b51075a9) Reviewed-by: Qt Cherry-pick Bot --- src/corelib/doc/src/includes/models.qdocinc | 14 ++++++++++++++ src/corelib/itemmodels/qabstractitemmodel.cpp | 4 +++- 2 files changed, 17 insertions(+), 1 deletion(-) create mode 100644 src/corelib/doc/src/includes/models.qdocinc diff --git a/src/corelib/doc/src/includes/models.qdocinc b/src/corelib/doc/src/includes/models.qdocinc new file mode 100644 index 00000000000..cf840b1cae8 --- /dev/null +++ b/src/corelib/doc/src/includes/models.qdocinc @@ -0,0 +1,14 @@ +//! [thread-safety-section1] +\section1 Thread safety + +Being a \l {Accessing QObject Subclasses from Other Threads}{subclass of +QObject}, \1 is not \l {Reentrancy and Thread-Safety}{thread-safe}. Any \1 +model-related API should only be called from the thread the model object lives +in. If the \1 is connected with a view, that means the GUI thread, as that is +where the view lives, and it will call into the model from the GUI thread. +Using a background thread to populate or modify the contents of a model is +possible, but requires care, as the background thread cannot call any +model-related API directly. Instead, you should queue the updates and apply +them in the main thread. This can be done with \l {Signals and Slots Across +Threads}{queued connections}. +//! [thread-safety-section1] diff --git a/src/corelib/itemmodels/qabstractitemmodel.cpp b/src/corelib/itemmodels/qabstractitemmodel.cpp index a042dceca07..f7b35ea7965 100644 --- a/src/corelib/itemmodels/qabstractitemmodel.cpp +++ b/src/corelib/itemmodels/qabstractitemmodel.cpp @@ -1499,6 +1499,8 @@ void QAbstractItemModel::resetInternalData() rows to the model, \l{QAbstractItemModel::}{beginInsertRows()} and \l{QAbstractItemModel::}{endInsertRows()} must be called. + \include models.qdocinc {thread-safety-section1}{QAbstractItemModel} + \sa {Model Classes}, {Model Subclassing Reference}, QModelIndex, QAbstractItemView, {Using drag and drop with item views}, {Simple Tree Model Example}, {Editable Tree Model Example}, @@ -3730,7 +3732,7 @@ void QAbstractItemModel::multiData(const QModelIndex &index, QModelRoleDataSpan \note Some general guidelines for subclassing models are available in the \l{Model Subclassing Reference}. - \note + \include models.qdocinc {thread-safety-section1}{QAbstractTableModel} \sa {Model Classes}, QAbstractItemModel, QAbstractListModel */