[Development] Community effort in updating Qt5 docs -- QThread focus

[Chris Meyer]

On Sat, Sep 29, 2012 at 12:59 AM, Sze Howe Koh <szehowe.koh at gmail.com> wrote:
> Hi all,
>
> As part of the effort to polishing the documentation for Qt 5
> (http://community.kde.org/Qt5/Documentation), I'm taking on the
> QThread-related docs, which have been outdated since Qt 4.4, causing much
> confusion across the internet.
>
> Before submitting it to Gerrit, I'd like to ask for help in vetting the text
> for optimal clarity, brevity, coverage and correctness.
>
> My draft for the QThread class reference is at
> http://qt-project.org/forums/viewthread/20691/. If you could spare a few
> minutes to read it and provide comments, either on the forum of this mailing
> list, I would be very grateful.
>
>
> Thanks in advance,
> Sze-Howe

The documentation promotes the idea of using 'moveToThread' as a
preferred threading mechanism. However, we've found that moveToThread
is full of pitfalls.

Particularly, an object must be deleted on the thread on which it
resides. This makes it difficult to manage the lifetime of objects
that have been moved to a thread via moveToThread. You need to
configure an independent mechanism to delete objects that have been
moved to thread (i.e. send a signal to the thread that it's about to
shutdown and allow the objects to deleteLater within the thread, which
also implies that you need to keep track of the objects that are
within the thread, which somewhat defeats the apparent simplicity of
moveToThread). Also, you cannot use the finished signal from the
thread since the thread will already be gone by then.

The bug will show up intermittently and differently on various
platforms and is difficult to debug if you don't know about the
problem. You'll just end up with spurious crashes (typically at quit
time), especially for networking objects.