Updating QThread docs (finally!)
-
Yes, I thought about posting a new forum thread before posting a response in this one. I will.
-
Hi all, some more updates made, based on suggestions from the mailing list and this forum. Comments and suggestions would be appreciated, as usual.
Changes:
- Added fact: Connecting finished() to deleteLater() became possible in Qt 4.8
- Added fact: sleep functions became public in Qt 5
- Added: Member function documentation (below, due to length constraints. I think the drafts for other pages shall be going on the wiki :P)
Questions:
- QThread::event() currently has a blank doc entry; what do developers need to know about it? From the source code, it provides handling of quit events, on top of QObject::event(). Does this need to be published?
=========================================================
DRAFT STARTS
Only modified member functions are shown: -Strikethroughs- = Deletions; Italics = Additionsh3. Member Function Documentation
h2. QThread::QThread(QObject * parent = 0)
Constructs a new -thread with the given parent.- QThread to manage a new thread. The parent takes ownership of the QThread. The thread does not begin executing until start() is called.
See also start().h2. QThread::~QThread()
Destroys the -thread- QThread.
Note that deleting a QThread object will not stop the execution of the thread it -represents- manages. Deleting a running QThread (i.e. isFinished() returns false) will probably result in a program crash. -You can wait() on a thread to make sure that it has finished.- Wait for the finished() signal before deleting the QThread.
h2. QThread * QThread::currentThread() [static]
Returns a pointer to a QThread which -represents- manages the currently executing thread.
h2. void QThread::run() [virtual protected]
The starting point for the thread. After calling start(), the newly created thread calls this function. The default implementation simply calls exec().
You can reimplement -ed- this function to -do other useful work- facilitate advanced thread management. Returning from this method will end the execution of the thread.
See also start() and wait().
h2. void QThread::start(Priority priority = InheritPriority) [slot]
Begins execution of the thread by calling run() -, which should be reimplemented in a QThread subclass to contain your code- . The operating system will schedule the thread according to the priority parameter. If the thread is already running, this function does nothing.
The effect of the priority parameter is dependent on the operating system's scheduling policy. In particular, the priority will be ignored on systems that do not support thread priorities (such as on Linux, see http://linux.die.net/man/2/sched_setscheduler for more details).
See also run() and terminate().
=========================================================
DRAFT ENDSTODO:
~ Add version info for functions introduced in Qt 5
~ Add "\override" to QThread::event()
~ Give sleep(), msleep() and usleep() the same wording -
Random thoughts:
- I wouldn't use the word "thread manager". I do understand what you try to stress, but a thread manager sounds more like an object managing more than one thread.
- For event, just put \override without any further explaination.
- "Every thread has its own stack." is a quite obvious statement to me... people failing to grasp thread basics probably shouldn't be playing with QThread at all
- Instead of stressing that various sleep methods are public in 5.0, I would stress that their usage is very likely a symptom of bad programming :-P cf. http://qt-project.org/wiki/Threads_Events_QObjects#92dd35cc61ffc41d02defdcef071856d
-
[quote author="peppe" date="1349024940"]
- I wouldn't use the word "thread manager". I do understand what you try to stress, but a thread manager sounds more like an object managing more than one thread.[/quote]Good point. So "thread" implies that QThread IS-A thread, but "thread manager" implies a one-to-many relationship. What's a good alternative? I can think of:
"[The constructor] constructs a new..."
- "... thread controller."
- "... thread control interface."
- "... object that manages a thread."
- "... QThread."
- "... QThread that manages a new thread."
- -"... QThread, along with the thread that it will manage."- Edit: Incorrect
(Side note: Maybe the name of the class itself should be changed for the next version of Qt. But then again, people don't seem to struggle much when using QDir, which is-not-a dir)
[quote author="peppe" date="1349024940"]
- For event, just put \override without any further explaination.
- "Every thread has its own stack." is a quite obvious statement to me... people failing to grasp thread basics probably shouldn't be playing with QThread at all[/quote]Done, and removed.
[quote author="peppe" date="1349024940"]
- Instead of stressing that various sleep methods are public in 5.0, I would stress that their usage is very likely a symptom of bad programming :-P cf. http://qt-project.org/wiki/Threads_Events_QObjects#92dd35cc61ffc41d02defdcef071856d[/quote]
Good point. I've stressed that forced sleeps should be unnecessary given that Qt is an event-driven framework, and urged readers to consider QTimer instead for their needs. (Are there any other common reasons people force a thread to sleep? I've never actually used these functions myself)
Continuing the train of thought, would you say that wait()-ing is sub-optimal, too? Personally, I listen for the finished() signal, and have never used wait().
-
Updated, to encourage developers to listen for finished() instead of using wait(). Also edited the constructor/destructor descriptions.
I'm planning to submit this to Gerrit in 48 hours, if there are no more comments from here or the mailing list. Thanks for all your input so far!
-
Gerritted: (Qt5) https://codereview.qt-project.org/36301
Edit: (Qt4) https://codereview.qt-project.org/36566 -
-
I did; the announcement came a few hours after my original patch set. I didn't pay much attention to it at first as I thought it was for the qtdoc repo only (QThread is in qtbase). I've asked Eskil for clarification though.
-
Thnaks a lot for your effort, mate.
-
Pleasure :)
