Updating Qt's threading overview docs
-
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 -
Sounds very good and interesting
Locking forward to have a short look at the new ones... -
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!
-
-
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
-
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.
-
@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.
