Updating Qt's threading overview docs

JKSH

Hi all,
I'm about to start polishing the overview documentation for threading in Qt. Below is a list of major problems I identified, as well as my plan of attack, for your review. If anyone has comments or suggestions, I'd love to hear them!

Finally, I'd like to ask for advice regarding the reading list. The current docs recommend these external reading materials:

Threads Primer: A Guide to Multithreaded Programming
Thread Time: The Multithreaded Programming Guide
Pthreads Programming: A POSIX Standard for Better Multiprocessing
Win32 Multithreaded Programming
Video tutorials about threads from the Training Day at Qt Developer Days 2009
Advanced Qt Programming by Mark Summerfield, Prentice Hall

I haven't read (or watched) these myself; are they still good resources to recommend? Or should we remove/replace some items?

Problems
The current overview documentation for threading contains these issues:

The docs showcase poor programming practices (e.g. subclassing QThread, using threads to implement a clock)
The docs are fragmented. There was originally one series of pages [1], and one standalone page [2] was added on later. However, that page is long, covers multiple topics, and overlaps with the series.
The series is QThread-centric. QtConcurrent seems tacked on, and QRunnable isn't mentioned at all

Plan
This is my proposal for addressing the problems above and improving the quality overall:

Merge the standalone page into the series, redistributing sections for better flow
Introduce all of Qt's threading technologies together (QThread, QRunnable, QtConcurrent)
Rewrite examples as necessary
Incorporate gems from http://qt-project.org/wiki/Threads_Events_QObjects
General copy editing

References
[1] http://doc-snapshot.qt-project.org/5.0/qtcore/threads.html -- the "Topics" list links to the rest of the series
[2] http://doc-snapshot.qt-project.org/5.0/qtcore/thread-basics.html

giesbert

Sounds very good and interesting
Locking forward to have a short look at the new ones...

JKSH

Hi all, the first draft is ready (https://docs.google.com/file/d/0B71n5SNZeRJyMEJkRUk5dWZiNm8/edit ) -- every page has been edited, except for "Threads and QObjects". See my original post for links to the original version.

Broad structure (Section title + summary)

Threading Basics
......... Introduction to multithreading (generic)
When (Not) to Use Threads in Qt
......... Help users decide if their program needs multiple threads
......... Highlight Qt's event-driven alternatives to threads
Multithreading Technologies in Qt
......... Introduce, then compare + contrast QThread, QRunnable, and Qt Concurrent
Reentrancy and Thread-Safety
......... Introduce these background concepts
......... Briefly describe Qt class' reentrancy
Synchronizing Threads
......... Show how to maintain data integrity when multithreading
Threads and QObjects
......... Show how to properly use Qobjects across threads
Thread Support in Qt Modules
......... Specialized info regarding specific modules
Further reading

Feedback request
The most drastic changes have occurred in Sections #1-#3. It's a long read I know, but if anyone's willing to spare some time to skim through and provide some feedback, I'd be most grateful.

Specifically, I'm looking for feedback on:

Does the structure make sense?
Is the level of detail appropriate?

Also, I'd like advice on:

Are the reading lists in #1 and #8 still good, or should we replace/remove them?
#7 feels rather incomplete -- Is there more? Where can I find info about other modules (short of trawling through the class refs)?

Thanks!

JKSH

Draft 2: https://docs.google.com/file/d/0B71n5SNZeRJyQzNhd2FuUWpuSVE/edit

Changes:

Renamed "Threads and QObjects" --> "QObjects and Inter-Thread Communication"
Fleshed out the concept of thread affinity, and how to manage it
Minor restructuring of the rest of the series

KA51O

Great work so far. I especially like what you did in chapter 2 and 3. The guidelines on when to use QRunnable QtConcurrent and QThread are very helpfull.

JKSH

@KA51O, thank you for reading and for your feedback!

I've made a Draft 3: https://docs.google.com/open?id=0B71n5SNZeRJyNzZ6U0tVUUM5bUk

No big changes this time, only rephrasing. I know if I sit down and stare at it I'll keep finding things to change... so I think I'll submit it now. Fingers crossed that it's suitable for, and in time for, the Qt 5 release.