This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH v2 2/4] manual: Add documentation for pthread_tryjoin_np and pthread_timedjoin_np
On 18/09/2019 05:30, Mike Crowe wrote:
> This documentation isn't perfect, but it's better than nothing and can
> hopefully act as a basis for future improvement. In particular, although
> I'm certain that the functions are MT-Safe, I'm not sure about the rest of
> the @safety line.
>
> Yann Droneaud pointed out that pthread_timedjoin_np would wait forever if
> the timeout parameter is passed as NULL. Since it's now too late to change
> that, I've documented it.
To which semantic do you think it would be better to change? Since this
symbol are not yet in POSIX there still the possibility to change it
by using a new plus a compat symbol.
>
> * manual/threads.texi: Add brief documentation for
> pthread_tryjoin_np and pthread_timedjoin_np.
LGTM, thanks.
> ---
> ChangeLog | 5 +++++
> manual/threads.texi | 26 ++++++++++++++++++++++++--
> 2 files changed, 29 insertions(+), 2 deletions(-)
>
> diff --git a/ChangeLog b/ChangeLog
> index d7943ff..94ee860 100644
> --- a/ChangeLog
> +++ b/ChangeLog
> @@ -1,5 +1,10 @@
> 2019-09-18 Mike Crowe <mac@mcrowe.com>
>
> + * manual/threads.texi: Add brief documentation for
> + pthread_tryjoin_np and pthread_timedjoin_np.
> +
> +2019-09-18 Mike Crowe <mac@mcrowe.com>
> +
> * nptl/tst-join3.c: Use libsupport.
>
> 2019-09-18 Stefan Liebler <stli@linux.ibm.com>
> diff --git a/manual/threads.texi b/manual/threads.texi
> index 0e5e84a..8dcfc53 100644
> --- a/manual/threads.texi
> +++ b/manual/threads.texi
> @@ -727,6 +727,30 @@ rather than @code{CLOCK_REALTIME}. Currently, @var{clockid} must be either
> returned.
> @end deftypefun
>
> +@comment pthread.h
> +@comment GNU extension
> +@deftypefun int pthread_tryjoin_np (pthread_t *@var{thread},
> + void **@var{thread_return})
> +@standards{GNU, pthread.h}
> +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
> +Behaves like @code{pthread_join} except that it will return @code{EBUSY}
> +immediately if the thread specified by @var{thread} has not yet terminated.
> +@end deftypefun
> +
Ok.
> +@comment pthread.h
> +@comment GNU extension
> +@deftypefun int pthread_timedjoin_np (pthread_t *@var{thread},
> + void **@var{thread_return},
> + const struct timespec *@var{abstime})
> +@standards{GNU, pthread.h}
> +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
> +Behaves like @code{pthread_tryjoin_np} except that it will block until the
> +absolute time @var{abstime} measured against @code{CLOCK_REALTIME} is
> +reached if the thread has not terminated by that time and return
> +@code{EBUSY}. If @var{abstime} is equal to @code{NULL} then the function
> +will wait forever in the same way as @code{pthread_join}.
> +@end deftypefun
> +
> @c FIXME these are undocumented:
> @c pthread_atfork
> @c pthread_attr_destroy
> @@ -844,6 +868,4 @@ returned.
> @c pthread_spin_trylock
> @c pthread_spin_unlock
> @c pthread_testcancel
> -@c pthread_timedjoin_np
> -@c pthread_tryjoin_np
> @c pthread_yield
>
Ok.