On Mon, 8 Aug 2022 02:33:13 GMT, David Holmes <dhol...@openjdk.org> wrote:
>> src/java.base/share/classes/java/lang/Thread.java line 73:
>>
>>> 71: * or if its {@code run} method completes abruptly and the appropriate
>>> 72: * {@linkplain Thread.UncaughtExceptionHandler uncaught exception
>>> handler} completes
>>> 73: * normally or abruptly. With no code left to run, the thread has
>>> completed execution.
>>
>> I'm in two minds about introducing the UHE in paragraph 3 but probably okay
>> as you kinda have to mention it when defining termination. There's a lot
>> more to this story when you have agents in the picture but I'll not go
>> there. I wonder if we can do something with the last sentence that includes
>> the word "terminated". We use "terminated" in several places and it would be
>> clearer if this sentence were to end with something like "... the thread has
>> completes execution, and is terminated" (it could link to isAlive or
>> Thread.State#TERMINATED).
>>
>> Given that the join method is introduced as the method to wait for a thread
>> to terminate then it could be part of this paragraph rather than a single
>> sentence paragraph.
>
> I would also suggest that the join() sentence simply be the last sentence of
> the above paragraph:
>
>> The join method can be be used to wait for a thread to terminate.
The whole paragraph is about thread termination, so I don't think we need to
say "terminate" again in the last sentence. We could mention isAlive or the
TERMINATED state, but that brings in Thread.State which which require a
discussion of the thread's life cycle.
The "join" sentence was kind of tacked on to the end of a paragraph in the
original text; Alex suggested that I separate it into its own paragraph when we
were working on the "termination" paragraph. Alex doesn't mind single-sentence
paragraphs, which isn't my preference. But tacking the "join" sentence onto the
end of the "termination" paragraph actually doesn't make any sense. Termination
is something that happens to _this_ thread. The join method is called from
_another_ thread, and this implicit shift of viewpoint would weaken the
paragraph.
Frankly I think there needs to be a separate editorial pass over the Thread
docs. I know they were just rewritten in JDK 19, but there are some odd things
about it. The Thread.State life cycle isn't explained and isn't referenced by
methods such as start() and isAlive(). Also, various mentions of uncaught
exception handling talk about a thread's abrupt termination. There isn't any
such thing; a _method_ can complete normally or abruptly, and when a thread's
run() method completes either way, the thread simply terminates.
-------------
PR: https://git.openjdk.org/jdk/pull/9437
