This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
[PATCH v2 2/4] manual: Add documentation for pthread_tryjoin_np and pthread_timedjoin_np
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.
* manual/threads.texi: Add brief documentation for
pthread_tryjoin_np and pthread_timedjoin_np.
---
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
+
+@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
--
git-series 0.9.1