Document the dangers of executing the event loop in QML API

Change-Id: I0294dd85fcc60615240a33c6e4a108fbde17a4bc
Reviewed-by: Bea Lam <bea.lam@nokia.com>

diff --git a/src/qml/doc/src/performance.qdoc b/src/qml/doc/src/performance.qdoc
index 91c9bbb..f6e56c9 100644 (file)
--- a/src/qml/doc/src/performance.qdoc
+++ b/src/qml/doc/src/performance.qdoc
@@ -47,6 +47,14 @@ never spend more than a couple of milliseconds per frame within blocking functio
 Failure to do so will result in skipped frames, which has a drastic effect on the
 user experience.
 
+\note A pattern which is tempting, but should \e never be used, is creating your
+own QEventLoop or calling QCoreApplication::processEvents() in order to avoid
+blocking within a C++ code block invoked from QML. This is dangerous because
+when an event loop is entered in a signal handler or binding, the QML engine
+continues to run other bindings, animations, transitions, etc. Those bindings
+can then cause side effects which, for example, destroy the hierarchy containing
+your event loop.
+
 \section1 Profiling
 
 The most important tip is: use the QML profiler included with Qt Creator.  Knowing