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

[Sze Howe Koh]

On Sun, Sep 30, 2012 at 2:24 AM, Chris Meyer <cmeyer1969+qt at gmail.com>wrote:

> On Sat, Sep 29, 2012 at 11:04 AM, João Abecasis <joao at abecasis.name>
> wrote:
> > João Abecasis wrote:
> >> Chris Meyer wrote:
> >>> 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.
> >>
> >> Since Qt 4.8 you can connect QThread::finished to QObject::deleteLater
> >> and it should do the right thing in the appropriate thread.
> >
> > For reference, here's a link to the commit implementing this:
> >
> >
> http://qt.gitorious.org/qt/qt/commit/0c643b179c5154c50b61dba421016b7b48794720
>
> This looks like a great change to have. In any case, the overall
> problem, solution, and in what version it was implemented needs to be
> documented in the QThread documentation. I missed this
> commit-log-message-as-documentation before.



Yes, that change makes life a lot nicer; thanks for the reference, João.
So, is it safe to say now that the old pitfalls of moveToThread() have been
addressed? (as long as the user doesn't write "moveToThread(this)", of
course)

Is there a conventional way to document the version where a _behaviour_ is
introduced? I'm aware of the "\since" tag, but I believe that can only be
used for classes and functions. Should I just describe it in the main body
of the text?


Cheers,
Sze-Howe
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20120930/6689be89/attachment.html>