Browse files

Explain Qt copy-on-write a little bit better in the doxygen docs.

This probably still needs some examples.
  • Loading branch information...
daniel-kristjansson committed Jan 13, 2013
1 parent 95e61c6 commit 38af2c78bad85cf251d285a6bf29c89a916a9a56
Showing with 24 additions and 5 deletions.
  1. +24 −5 mythtv/docs/doxygen-architecture-document.cpp
@@ -27,11 +27,30 @@ by accident, maybe you want to go to the official
If you are new to Qt programming it is essential that you keep in mind
that almost all Qt objects are not thread-safe, including QString.
Almost all Qt container objects, including QString, make shallow copies
on assignment, the two copies of the object must only be used in one
thread unless you use a lock on the object. You can use the
QString::detach() on a QString to force a deep copy to be made instead,
which can then be used in another thread.
The Qt containers QMap, QSet, QHash, QString, QList, etc are
copy-on-write containers. This means that when you assign one
container from another the data isn't actually copied. Instead
a copy of a pointer to the data is made and the reference count
is increased. Then when you actually modify the date or get
a modifiable reference into the container an actual copy is
made. This means you can return one of these containers efficiently
from a function without needing C++11 support. This also means
these containers are a bit less efficient than their STL equivalents
most of the time. We still prefer them in MythTV code, especially
QString due to the extensive i18n support in Qt. QList is actually
equivalent to an STL deque. We also use the STL style iterators. This
is both because it makes it easier to switch to an STL container in
the rare case when it is necessary, such as when we need a reverse
iterator iterator, and because they are more efficient than the
Java style iterators that Qt also supports.
In Qt 3.x and Qt 4.0 assignment of one Qt copy-on-write was
not yet thread-safe. Because of this you will see a number of
::detach() calls in MythTV code. These calls force a deep copy
to be made immediately and should either be removed or a comment
should be added in the rare case where this is done as an
optimization and not just a hold-over from when copy-on-write
wasn't yet thread-safe in Qt 4.0 and earlier.
There are some special dangers when
\ref qobject_dangers "using QObject" outside the Qt event thread.

0 comments on commit 38af2c7

Please sign in to comment.