Re: Man page bug report about pthread_join

Re: Man page bug report about pthread_join

[Michael Kerrisk (man-pages)]

Hello 王守堰,

On 08/24/2016 09:11 PM, 王守堰 wrote:
> Hi:
>   I have checked the newest version of pthread_join at
> *http://man7.org/linux/man-pages/man3/pthread_join.3.html
> <http://man7.org/linux/man-pages/man3/pthread_join.3.html>*
>   I think there exists something wront in this sentence:
> 
> If *retval* is not NULL, then *pthread_join*() copies the exit status of
>        the target thread (i.e., the value that the target thread supplied to
>        pthread_exit(3)
> <http://man7.org/linux/man-pages/man3/pthread_exit.3.html>) into the
> location pointed to by **retval*.
> 
> I think it should be "into the location pointed to by *retval" *or
> "into **retval".*
> 
> Because the actual behavior of pthread_join() is like:  *retval = exit_status;
> 
> But the current man page description means: *(*retval) = exit_status;
> 
> Do you agree with me?
> 
> Hope your reply.

I agree that there is a bit of confusion in the wording of the page.
I changed this paragraph to read:

       If retval is not NULL, then pthread_join() copies the exit  status
       of  the target thread (i.e., the value that the target thread sup‐
       plied to pthread_exit(3)) into the location pointed to by  retval.
       If the target thread was canceled, then PTHREAD_CANCELED is placed
       in the location pointed to by retval.

Okay?

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Man page bug report about pthread_join

[Mats Wichmann]

On 08/28/2016 03:58 PM, Michael Kerrisk (man-pages) wrote:
> Hello 王守堰,
> 
> On 08/24/2016 09:11 PM, 王守堰 wrote:
>> Hi:
>>   I have checked the newest version of pthread_join at
>> *http://man7.org/linux/man-pages/man3/pthread_join.3.html
>> <http://man7.org/linux/man-pages/man3/pthread_join.3.html>*
>>   I think there exists something wront in this sentence:
>>
>> If *retval* is not NULL, then *pthread_join*() copies the exit status of
>>        the target thread (i.e., the value that the target thread supplied to
>>        pthread_exit(3)
>> <http://man7.org/linux/man-pages/man3/pthread_exit.3.html>) into the
>> location pointed to by **retval*.
>>
>> I think it should be "into the location pointed to by *retval" *or
>> "into **retval".*
>>
>> Because the actual behavior of pthread_join() is like:  *retval = exit_status;
>>
>> But the current man page description means: *(*retval) = exit_status;
>>
>> Do you agree with me?
>>
>> Hope your reply.
> 
> I agree that there is a bit of confusion in the wording of the page.
> I changed this paragraph to read:
> 
>        If retval is not NULL, then pthread_join() copies the exit  status
>        of  the target thread (i.e., the value that the target thread sup‐
>        plied to pthread_exit(3)) into the location pointed to by  retval.
>        If the target thread was canceled, then PTHREAD_CANCELED is placed
>        in the location pointed to by retval.
> 
> Okay?
> 
> Cheers,

The wording here comes off kind of awkward. How about this as an
alternate thought:

If retval is not NULL, pthread_join shall return a pointer to a location
containing the exit status of the target thread in retval. If the target
thread was canceled, the exit status will indicate PTHREAD_CANCELED.

I don't think the aside (i.e. the value that ...) adds any value.

While we're here, this page doesn't mention the justification for
joining in the first place, which is to have an opportunity to clean up
after a thread exits - or rather, it is mentioned, but in a negative
sense ("failure to join with a thread that is joinable..."). I don't
immediately have a proposal, but could think about it if anyone believes
that's a good idea.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Man page bug report about pthread_join

[Michael Kerrisk (man-pages)]

Hello Mats,

On 08/30/2016 04:41 AM, Mats Wichmann wrote:
> On 08/28/2016 03:58 PM, Michael Kerrisk (man-pages) wrote:
>> Hello 王守堰,
>>
>> On 08/24/2016 09:11 PM, 王守堰 wrote:
>>> Hi:
>>>   I have checked the newest version of pthread_join at
>>> *http://man7.org/linux/man-pages/man3/pthread_join.3.html
>>> <http://man7.org/linux/man-pages/man3/pthread_join.3.html>*
>>>   I think there exists something wront in this sentence:
>>>
>>> If *retval* is not NULL, then *pthread_join*() copies the exit status of
>>>        the target thread (i.e., the value that the target thread supplied to
>>>        pthread_exit(3)
>>> <http://man7.org/linux/man-pages/man3/pthread_exit.3.html>) into the
>>> location pointed to by **retval*.
>>>
>>> I think it should be "into the location pointed to by *retval" *or
>>> "into **retval".*
>>>
>>> Because the actual behavior of pthread_join() is like:  *retval = exit_status;
>>>
>>> But the current man page description means: *(*retval) = exit_status;
>>>
>>> Do you agree with me?
>>>
>>> Hope your reply.
>>
>> I agree that there is a bit of confusion in the wording of the page.
>> I changed this paragraph to read:
>>
>>        If retval is not NULL, then pthread_join() copies the exit  status
>>        of  the target thread (i.e., the value that the target thread sup‐
>>        plied to pthread_exit(3)) into the location pointed to by  retval.
>>        If the target thread was canceled, then PTHREAD_CANCELED is placed
>>        in the location pointed to by retval.
>>
>> Okay?
>>
>> Cheers,
> 
> The wording here comes off kind of awkward. How about this as an
> alternate thought:
> 
> If retval is not NULL, pthread_join shall return a pointer to a location
> containing the exit status of the target thread in retval. If the target
> thread was canceled, the exit status will indicate PTHREAD_CANCELED.

I guess it's in the eye of the beholder. To me, your phrasing sounds a
little awkward :-}. So, for the moment I'm inclined to leave things be.

> I don't think the aside (i.e. the value that ...) adds any value.

Hmm. I don't so far agree. I think it's a helpful tip to the reader to 
let them know where this exit status comes from. Why do you think it 
isn't?

> While we're here, this page doesn't mention the justification for
> joining in the first place, which is to have an opportunity to clean up
> after a thread exits - or rather, it is mentioned, but in a negative
> sense ("failure to join with a thread that is joinable..."). I don't
> immediately have a proposal, but could think about it if anyone believes
> that's a good idea.

I added a sentence at the end of the first paragraph in NOTES:

       After a successful call to pthread_join(), the caller  is  guaran‐
       teed  that  the target thread has terminated.  <<The caller may then
       choose to do any clean-up that is required  after  termination  of
       the  thread  (e.g.,  freeing  memory  or other resources that were
       allocated to the target thread).>>

Helpful?

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Man page bug report about pthread_join

[Mats Wichmann]

On 08/29/2016 01:59 PM, Michael Kerrisk (man-pages) wrote:
> Hello Mats,

>> The wording here comes off kind of awkward. How about this as an
>> alternate thought:
>>
>> If retval is not NULL, pthread_join shall return a pointer to a location
>> containing the exit status of the target thread in retval. If the target
>> thread was canceled, the exit status will indicate PTHREAD_CANCELED.
> 
> I guess it's in the eye of the beholder. 

of course.


>> While we're here, this page doesn't mention the justification for
>> joining in the first place, which is to have an opportunity to clean up
>> after a thread exits - or rather, it is mentioned, but in a negative
>> sense ("failure to join with a thread that is joinable..."). I don't
>> immediately have a proposal, but could think about it if anyone believes
>> that's a good idea.
> 
> I added a sentence at the end of the first paragraph in NOTES:
> 
>        After a successful call to pthread_join(), the caller  is  guaran‐
>        teed  that  the target thread has terminated.  <<The caller may then
>        choose to do any clean-up that is required  after  termination  of
>        the  thread  (e.g.,  freeing  memory  or other resources that were
>        allocated to the target thread).>>
> 
> Helpful?

Yes, I think that improves things.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Man page bug report about pthread_join

[Michael Kerrisk (man-pages)]

On 08/30/2016 09:48 AM, Mats Wichmann wrote:
> On 08/29/2016 01:59 PM, Michael Kerrisk (man-pages) wrote:
>> Hello Mats,
> 
>>> The wording here comes off kind of awkward. How about this as an
>>> alternate thought:
>>>
>>> If retval is not NULL, pthread_join shall return a pointer to a location
>>> containing the exit status of the target thread in retval. If the target
>>> thread was canceled, the exit status will indicate PTHREAD_CANCELED.
>>
>> I guess it's in the eye of the beholder. 
> 
> of course.
> 
> 
>>> While we're here, this page doesn't mention the justification for
>>> joining in the first place, which is to have an opportunity to clean up
>>> after a thread exits - or rather, it is mentioned, but in a negative
>>> sense ("failure to join with a thread that is joinable..."). I don't
>>> immediately have a proposal, but could think about it if anyone believes
>>> that's a good idea.
>>
>> I added a sentence at the end of the first paragraph in NOTES:
>>
>>        After a successful call to pthread_join(), the caller  is  guaran‐
>>        teed  that  the target thread has terminated.  <<The caller may then
>>        choose to do any clean-up that is required  after  termination  of
>>        the  thread  (e.g.,  freeing  memory  or other resources that were
>>        allocated to the target thread).>>
>>
>> Helpful?
> 
> Yes, I think that improves things.

Thanks.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html