[Guile-commits] 01/02: Update join-thread docs

[Andy Wingo]

wingo pushed a commit to branch master
in repository guile.

commit f927c70d4280a9644b9997108d67da2addb3eb65
Author: Andy Wingo <address@hidden>
Date:   Mon Nov 21 18:34:41 2016 +0100

    Update join-thread docs
    
    * doc/ref/api-scheduling.texi (Threads): Joining a foreign thread is an
      error.
    * NEWS: Update.
---
 NEWS                        |    9 ++++++++-
 doc/ref/api-scheduling.texi |   16 +++++++++-------
 2 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/NEWS b/NEWS
index 9221739..05acbf1 100644
--- a/NEWS
+++ b/NEWS
@@ -54,7 +54,7 @@ deprecated; use `scm_timed_lock_mutex' instead.
 
 It used to be that `unlock-mutex' included `wait-condition-variable'
 functionality.  This has been deprecated; use SRFI-18 if you want this
-behavior from `mutex-unlock!'.  Relatedly, `scm_unlock_mutex_timed is
+behavior from `mutex-unlock!'.  Relatedly, `scm_unlock_mutex_timed' is
 deprecated; use `scm_unlock_mutex' instead.
 
 ** Removed `unchecked-unlock' mutex flag
@@ -73,6 +73,13 @@ The `set-thread-cleanup!' and `thread-cleanup' functions 
that were added
 in Guile 2.0 to support cleanup after thread cancellation are no longer
 needed, since threads can declare cleanup handlers via `dynamic-wind'.
 
+** Only threads created by Guile are joinable
+
+`join-thread' used to work on "foreign" threads that were not created by
+Guile itself, though their join value was always `#f'.  This is no
+longer the case; attempting to join a foreign thread will throw an
+error.
+
 * New deprecations
 ** Arbiters deprecated
 
diff --git a/doc/ref/api-scheduling.texi b/doc/ref/api-scheduling.texi
index 1f5d17f..1087bfe 100644
--- a/doc/ref/api-scheduling.texi
+++ b/doc/ref/api-scheduling.texi
@@ -88,13 +88,15 @@ Return @code{#t} ff @var{obj} is a thread; otherwise, return
 @deffn {Scheme Procedure} join-thread thread [timeout [timeoutval]]
 @deffnx {C Function} scm_join_thread (thread)
 @deffnx {C Function} scm_join_thread_timed (thread, timeout, timeoutval)
-Wait for @var{thread} to terminate and return its exit value.  Threads
-that have not been created with @code{call-with-new-thread} or
address@hidden have an exit value of @code{#f}.  When
address@hidden is given, it specifies a point in time where the waiting
-should be aborted.  It can be either an integer as returned by
address@hidden or a pair as returned by @code{gettimeofday}.
-When the waiting is aborted, @var{timeoutval} is returned (if it is
+Wait for @var{thread} to terminate and return its exit value.  Only
+threads that were created with @code{call-with-new-thread} or
address@hidden can be joinable; attempting to join a foreign
+thread will raise an error.
+
+When @var{timeout} is given, it specifies a point in time where the
+waiting should be aborted.  It can be either an integer as returned by
address@hidden or a pair as returned by @code{gettimeofday}.  When
+the waiting is aborted, @var{timeoutval} is returned (if it is
 specified; @code{#f} is returned otherwise).
 @end deffn