From patchwork Wed Sep 18 12:30:54 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mike Crowe X-Patchwork-Id: 34564 Received: (qmail 67465 invoked by alias); 18 Sep 2019 12:31:18 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 67365 invoked by uid 89); 18 Sep 2019 12:31:17 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-22.8 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, RCVD_IN_DNSWL_LOW autolearn=ham version=3.3.1 spammy=act, HContent-Transfer-Encoding:8bit X-HELO: avasout07.plus.net X-Clacks-Overhead: "GNU Terry Pratchett" X-CM-Score: 0.00 From: Mike Crowe To: libc-alpha@sourceware.org Cc: Mike Crowe Subject: [PATCH v2 2/4] manual: Add documentation for pthread_tryjoin_np and pthread_timedjoin_np Date: Wed, 18 Sep 2019 13:30:54 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 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 + * manual/threads.texi: Add brief documentation for + pthread_tryjoin_np and pthread_timedjoin_np. + +2019-09-18 Mike Crowe + * nptl/tst-join3.c: Use libsupport. 2019-09-18 Stefan Liebler 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