From 499957eb8b1c5150823f05f40f32b04ba13b1640 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thorbj=C3=B8rn=20Martsum?= Date: Tue, 24 Sep 2013 16:42:22 +0200 Subject: Improve implicit shared documentation a bit Task-number: QTBUG-27061 Change-Id: I66e000a9f59fda3654066013e6e78c3ba6fd27fe Reviewed-by: Mitch Curtis Reviewed-by: Thiago Macieira --- src/corelib/tools/qhash.cpp | 10 ++++++++++ src/corelib/tools/qlinkedlist.cpp | 14 +++++++++++--- src/corelib/tools/qlist.cpp | 10 ++++++++++ src/corelib/tools/qmap.cpp | 10 ++++++++++ src/corelib/tools/qset.qdoc | 14 ++++++++++---- src/corelib/tools/qvector.cpp | 10 ++++++++++ 6 files changed, 61 insertions(+), 7 deletions(-) (limited to 'src/corelib/tools') diff --git a/src/corelib/tools/qhash.cpp b/src/corelib/tools/qhash.cpp index 7f6feaf8a0..f14fac00b8 100644 --- a/src/corelib/tools/qhash.cpp +++ b/src/corelib/tools/qhash.cpp @@ -1594,6 +1594,11 @@ void QHashData::checkSanity() need to keep iterators over a long period of time, we recommend that you use QMap rather than QHash. + \warning Iterators on implicitly shared containers do not work + exactly like STL-iterators. You should avoid copying a container + while iterators are active on that container. For more information, + read \l{Implicit sharing iterator problem}. + \sa QHash::const_iterator, QMutableHashIterator */ @@ -1791,6 +1796,11 @@ void QHashData::checkSanity() internal data structure. If you need to keep iterators over a long period of time, we recommend that you use QMap rather than QHash. + \warning Iterators on implicitly shared containers do not work + exactly like STL-iterators. You should avoid copying a container + while iterators are active on that container. For more information, + read \l{Implicit sharing iterator problem}. + \sa QHash::iterator, QHashIterator */ diff --git a/src/corelib/tools/qlinkedlist.cpp b/src/corelib/tools/qlinkedlist.cpp index 28319f3fda..e967163b8b 100644 --- a/src/corelib/tools/qlinkedlist.cpp +++ b/src/corelib/tools/qlinkedlist.cpp @@ -691,9 +691,12 @@ const QLinkedListData QLinkedListData::shared_null = { Multiple iterators can be used on the same list. If you add items to the list, existing iterators will remain valid. If you remove items from the list, iterators that point to the removed items - will become dangling iterators. However, because of how \l{implicit - sharing} works, you must not take a copy of a container while - iterators are active on that container. + will become dangling iterators. + + \warning Iterators on implicitly shared containers do not work + exactly like STL-iterators. You should avoid copying a container + while iterators are active on that container. For more information, + read \l{Implicit sharing iterator problem}. \sa QLinkedList::const_iterator, QMutableLinkedListIterator */ @@ -910,6 +913,11 @@ const QLinkedListData QLinkedListData::shared_null = { items from the list, iterators that point to the removed items will become dangling iterators. + \warning Iterators on implicitly shared containers do not work + exactly like STL-iterators. You should avoid copying a container + while iterators are active on that container. For more information, + read \l{Implicit sharing iterator problem}. + \sa QLinkedList::iterator, QLinkedListIterator */ diff --git a/src/corelib/tools/qlist.cpp b/src/corelib/tools/qlist.cpp index d8ccf2cc43..0811c3793e 100644 --- a/src/corelib/tools/qlist.cpp +++ b/src/corelib/tools/qlist.cpp @@ -1292,6 +1292,11 @@ void **QListData::erase(void **xi) iterators over a long period of time, we recommend that you use QLinkedList rather than QList. + \warning Iterators on implicitly shared containers do not work + exactly like STL-iterators. You should avoid copying a container + while iterators are active on that container. For more information, + read \l{Implicit sharing iterator problem}. + \sa QList::const_iterator, QMutableListIterator */ @@ -1542,6 +1547,11 @@ void **QListData::erase(void **xi) iterators over a long period of time, we recommend that you use QLinkedList rather than QList. + \warning Iterators on implicitly shared containers do not work + exactly like STL-iterators. You should avoid copying a container + while iterators are active on that container. For more information, + read \l{Implicit sharing iterator problem}. + \sa QList::iterator, QListIterator */ diff --git a/src/corelib/tools/qmap.cpp b/src/corelib/tools/qmap.cpp index ab9b1d23ab..4da9669a39 100644 --- a/src/corelib/tools/qmap.cpp +++ b/src/corelib/tools/qmap.cpp @@ -1215,6 +1215,11 @@ void QMapDataBase::freeData(QMapDataBase *d) items from the map, iterators that point to the removed items will become dangling iterators. + \warning Iterators on implicitly shared containers do not work + exactly like STL-iterators. You should avoid copying a container + while iterators are active on that container. For more information, + read \l{Implicit sharing iterator problem}. + \sa QMap::const_iterator, QMutableMapIterator */ @@ -1433,6 +1438,11 @@ void QMapDataBase::freeData(QMapDataBase *d) items from the map, iterators that point to the removed items will become dangling iterators. + \warning Iterators on implicitly shared containers do not work + exactly like STL-iterators. You should avoid copying a container + while iterators are active on that container. For more information, + read \l{Implicit sharing iterator problem}. + \sa QMap::iterator, QMapIterator */ diff --git a/src/corelib/tools/qset.qdoc b/src/corelib/tools/qset.qdoc index a0bc206014..e66a59a09c 100644 --- a/src/corelib/tools/qset.qdoc +++ b/src/corelib/tools/qset.qdoc @@ -643,8 +643,12 @@ \snippet code/doc_src_qset.cpp 10 - Multiple iterators can be used on the same set. However, you may - not attempt to modify the container while iterating on it. + Multiple iterators can be used on the same set. + + \warning Iterators on implicitly shared containers do not work + exactly like STL-iterators. You should avoid copying a container + while iterators are active on that container. For more information, + read \l{Implicit sharing iterator problem}. \sa QSet::const_iterator, QMutableSetIterator */ @@ -682,8 +686,10 @@ \snippet code/doc_src_qset.cpp 12 - Multiple iterators can be used on the same set. However, you may - not attempt to modify the container while iterating on it. + \warning Iterators on implicitly shared containers do not work + exactly like STL-iterators. You should avoid copying a container + while iterators are active on that container. For more information, + read \l{Implicit sharing iterator problem}. \sa QSet::iterator, QSetIterator */ diff --git a/src/corelib/tools/qvector.cpp b/src/corelib/tools/qvector.cpp index 11990d30b2..b9281c6915 100644 --- a/src/corelib/tools/qvector.cpp +++ b/src/corelib/tools/qvector.cpp @@ -957,6 +957,11 @@ iterators}. The STL-style non-const iterator is simply a typedef for "T *" (pointer to T). + \warning Iterators on implicitly shared containers do not work + exactly like STL-iterators. You should avoid copying a container + while iterators are active on that container. For more information, + read \l{Implicit sharing iterator problem}. + \sa QVector::begin(), QVector::end(), QVector::const_iterator, QMutableVectorIterator */ @@ -969,6 +974,11 @@ iterators}. The STL-style const iterator is simply a typedef for "const T *" (pointer to const T). + \warning Iterators on implicitly shared containers do not work + exactly like STL-iterators. You should avoid copying a container + while iterators are active on that container. For more information, + read \l{Implicit sharing iterator problem}. + \sa QVector::constBegin(), QVector::constEnd(), QVector::iterator, QVectorIterator */ -- cgit v1.2.3