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/doc/src/containers.qdoc | 14 +++++++++++--- src/corelib/doc/src/implicit-sharing.qdoc | 20 ++++++++++++-------- 2 files changed, 23 insertions(+), 11 deletions(-) (limited to 'src/corelib/doc/src') diff --git a/src/corelib/doc/src/containers.qdoc b/src/corelib/doc/src/containers.qdoc index ff2df9c020..fa26409d83 100644 --- a/src/corelib/doc/src/containers.qdoc +++ b/src/corelib/doc/src/containers.qdoc @@ -533,10 +533,18 @@ This problem doesn't occur with functions that return a const or non-const reference to a container. + \section3 Implicit sharing iterator problem + \l{Implicit sharing} has another consequence on STL-style - iterators: You must not take a copy of a container while - non-const iterators are active on that container. Java-style - iterators don't suffer from that limitation. + iterators: you should avoid copying a container while + iterators are active on that container. The iterators + point to an internal structure, and if you copy a container + you should be very careful with your iterators. E.g: + + \snippet code/doc_src_containers.cpp 24 + + The above example only shows a problem with QVector, but + the problem exists for all the implicitly shared Qt containers. \keyword foreach \section1 The foreach Keyword diff --git a/src/corelib/doc/src/implicit-sharing.qdoc b/src/corelib/doc/src/implicit-sharing.qdoc index 814f8140f3..1185fe8348 100644 --- a/src/corelib/doc/src/implicit-sharing.qdoc +++ b/src/corelib/doc/src/implicit-sharing.qdoc @@ -89,9 +89,12 @@ of data. Objects can easily be assigned, sent as function arguments, and returned from functions. - Implicit sharing takes place behind the scenes; the programmer - does not need to worry about it. Even in multithreaded - applications, implicit sharing takes place, as explained in + Implicit sharing mostly takes place behind the scenes; + the programmer rarely needs to worry about it. However, Qt's + container iterators have different behavior than those from + the STL. Read \l{Implicit sharing iterator problem}. + + In multithreaded applications, implicit sharing takes place, as explained in \l{Thread-Support in Qt Modules#Threads and Implicitly Shared Classes} {Threads and Implicitly Shared Classes}. @@ -105,9 +108,10 @@ greater than one. (This is often called \e {copy-on-write} or \e {value semantics}.) - An implicitly shared class has total control of its internal data. In + An implicitly shared class has control of its internal data. In any member functions that modify its data, it automatically detaches - before modifying the data. + before modifying the data. Notice, however, the special case with + container iterators; see \l{Implicit sharing iterator problem}. The QPen class, which uses implicit sharing, detaches from the shared data in all member functions that change the internal data. @@ -133,9 +137,9 @@ In this example, \c p1 and \c p2 share data until QPainter::begin() is called for \c p2, because painting a pixmap will modify it. - \warning Do not copy an implicitly shared container (QMap, - QVector, etc.) while you are iterating over it using an non-const - \l{STL-style iterators}{STL-style iterator}. + \warning Be careful with copying an implicitly shared container + (QMap, QVector, etc.) while you use + \l{STL-style iterators}{STL-style iterator}. See \l{Implicit sharing iterator problem}. \keyword implicitly shared classes \annotatedlist shared -- cgit v1.2.3