[Guile-commits] 02/02: Small api-scheduling.texi reorder

[Andy Wingo]

wingo pushed a commit to branch master
in repository guile.

commit efcc30fc34b49cf2a045457dafae11989ccc0b3d
Author: Andy Wingo <address@hidden>
Date:   Tue Oct 18 21:25:42 2016 +0200

    Small api-scheduling.texi reorder
    
    * doc/ref/api-scheduling.texi: Put "Threads" section at beginning of
      scheduling chapter.
---
 doc/ref/api-scheduling.texi |  279 ++++++++++++++++++++++---------------------
 1 file changed, 140 insertions(+), 139 deletions(-)

diff --git a/doc/ref/api-scheduling.texi b/doc/ref/api-scheduling.texi
index 1fb9ec7..a13208a 100644
--- a/doc/ref/api-scheduling.texi
+++ b/doc/ref/api-scheduling.texi
@@ -8,9 +8,9 @@
 @section Threads, Mutexes, Asyncs and Dynamic Roots
 
 @menu
+* Threads::                     Multiple threads of execution.
 * Asyncs::                      Asynchronous interrupts.
 * Atomics::                     Atomic references.
-* Threads::                     Multiple threads of execution.
 * Mutexes and Condition Variables:: Synchronization primitives.
 * Blocking::                    How to block properly in guile mode.
 * Critical Sections::           Avoiding concurrency and reentries.
@@ -21,6 +21,145 @@
 @end menu
 
 
address@hidden Threads
address@hidden Threads
address@hidden threads
address@hidden Guile threads
address@hidden POSIX threads
+
+Guile supports POSIX threads, unless it was configured with
address@hidden or the host lacks POSIX thread support.  When
+thread support is available, the @code{threads} feature is provided
+(@pxref{Feature Manipulation, @code{provided?}}).
+
+The procedures below manipulate Guile threads, which are wrappers around
+the system's POSIX threads.  For application-level parallelism, using
+higher-level constructs, such as futures, is recommended
+(@pxref{Futures}).
+
address@hidden {Scheme Procedure} all-threads
address@hidden {C Function} scm_all_threads ()
+Return a list of all threads.
address@hidden deffn
+
address@hidden {Scheme Procedure} current-thread
address@hidden {C Function} scm_current_thread ()
+Return the thread that called this function.
address@hidden deffn
+
address@hidden begin (texi-doc-string "guile" "call-with-new-thread")
address@hidden {Scheme Procedure} call-with-new-thread thunk [handler]
+Call @code{thunk} in a new thread and with a new dynamic state,
+returning the new thread.  The procedure @var{thunk} is called via
address@hidden
+
+When @var{handler} is specified, then @var{thunk} is called from
+within a @code{catch} with tag @code{#t} that has @var{handler} as its
+handler.  This catch is established inside the continuation barrier.
+
+Once @var{thunk} or @var{handler} returns, the return value is made
+the @emph{exit value} of the thread and the thread is terminated.
address@hidden deffn
+
address@hidden {C Function} SCM scm_spawn_thread (scm_t_catch_body body, void 
*body_data, scm_t_catch_handler handler, void *handler_data)
+Call @var{body} in a new thread, passing it @var{body_data}, returning
+the new thread.  The function @var{body} is called via
address@hidden
+
+When @var{handler} is address@hidden, @var{body} is called via
address@hidden with tag @code{SCM_BOOL_T} that has
address@hidden and @var{handler_data} as the handler and its data.  This
+catch is established inside the continuation barrier.
+
+Once @var{body} or @var{handler} returns, the return value is made the
address@hidden value} of the thread and the thread is terminated.
address@hidden deftypefn
+
address@hidden {Scheme Procedure} thread? obj
address@hidden {C Function} scm_thread_p (obj)
+Return @code{#t} ff @var{obj} is a thread; otherwise, return
address@hidden
address@hidden deffn
+
address@hidden begin (texi-doc-string "guile" "join-thread")
address@hidden {Scheme Procedure} join-thread thread [timeout [timeoutval]]
address@hidden {C Function} scm_join_thread (thread)
address@hidden {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
+specified; @code{#f} is returned otherwise).
address@hidden deffn
+
address@hidden {Scheme Procedure} thread-exited? thread
address@hidden {C Function} scm_thread_exited_p (thread)
+Return @code{#t} if @var{thread} has exited, or @code{#f} otherwise.
address@hidden deffn
+
address@hidden begin (texi-doc-string "guile" "yield")
address@hidden {Scheme Procedure} yield
+If one or more threads are waiting to execute, calling yield forces an
+immediate context switch to one of them. Otherwise, yield has no effect.
address@hidden deffn
+
address@hidden {Scheme Procedure} cancel-thread thread
address@hidden {C Function} scm_cancel_thread (thread)
+Asynchronously notify @var{thread} to exit.  Immediately after
+receiving this notification, @var{thread} will call its cleanup handler
+(if one has been set) and then terminate, aborting any evaluation that
+is in progress.
+
+Because Guile threads are isomorphic with POSIX threads, @var{thread}
+will not receive its cancellation signal until it reaches a cancellation
+point.  See your operating system's POSIX threading documentation for
+more information on cancellation points; note that in Guile, unlike
+native POSIX threads, a thread can receive a cancellation notification
+while attempting to lock a mutex.
address@hidden deffn
+
address@hidden {Scheme Procedure} set-thread-cleanup! thread proc
address@hidden {C Function} scm_set_thread_cleanup_x (thread, proc)
+Set @var{proc} as the cleanup handler for the thread @var{thread}.
address@hidden, which must be a thunk, will be called when @var{thread}
+exits, either normally or by being canceled.  Thread cleanup handlers
+can be used to perform useful tasks like releasing resources, such as
+locked mutexes, when thread exit cannot be predicted.
+
+The return value of @var{proc} will be set as the @emph{exit value} of
address@hidden
+
+To remove a cleanup handler, pass @code{#f} for @var{proc}.
address@hidden deffn
+
address@hidden {Scheme Procedure} thread-cleanup thread
address@hidden {C Function} scm_thread_cleanup (thread)
+Return the cleanup handler currently installed for the thread
address@hidden  If no cleanup handler is currently installed,
+thread-cleanup returns @code{#f}.
address@hidden deffn
+
+Higher level thread procedures are available by loading the
address@hidden(ice-9 threads)} module.  These provide standardized
+thread creation.
+
address@hidden macro make-thread proc arg @dots{}
+Apply @var{proc} to @var{arg} @dots{} in a new thread formed by
address@hidden using a default error handler that display
+the error to the current error port.  The @var{arg} @dots{}
+expressions are evaluated in the new thread.
address@hidden deffn
+
address@hidden macro begin-thread expr1 expr2 @dots{}
+Evaluate forms @var{expr1} @var{expr2} @dots{} in a new thread formed by
address@hidden using a default error handler that display
+the error to the current error port.
address@hidden deffn
+
+
 @node Asyncs
 @subsection Asynchronous Interrupts
 
@@ -188,144 +327,6 @@ checking if the return value is @code{eq?} to 
@var{expected}.
 @end deffn
 
 
address@hidden Threads
address@hidden Threads
address@hidden threads
address@hidden Guile threads
address@hidden POSIX threads
-
-Guile supports POSIX threads, unless it was configured with
address@hidden or the host lacks POSIX thread support.  When
-thread support is available, the @code{threads} feature is provided
-(@pxref{Feature Manipulation, @code{provided?}}).
-
-The procedures below manipulate Guile threads, which are wrappers around
-the system's POSIX threads.  For application-level parallelism, using
-higher-level constructs, such as futures, is recommended
-(@pxref{Futures}).
-
address@hidden {Scheme Procedure} all-threads
address@hidden {C Function} scm_all_threads ()
-Return a list of all threads.
address@hidden deffn
-
address@hidden {Scheme Procedure} current-thread
address@hidden {C Function} scm_current_thread ()
-Return the thread that called this function.
address@hidden deffn
-
address@hidden begin (texi-doc-string "guile" "call-with-new-thread")
address@hidden {Scheme Procedure} call-with-new-thread thunk [handler]
-Call @code{thunk} in a new thread and with a new dynamic state,
-returning the new thread.  The procedure @var{thunk} is called via
address@hidden
-
-When @var{handler} is specified, then @var{thunk} is called from
-within a @code{catch} with tag @code{#t} that has @var{handler} as its
-handler.  This catch is established inside the continuation barrier.
-
-Once @var{thunk} or @var{handler} returns, the return value is made
-the @emph{exit value} of the thread and the thread is terminated.
address@hidden deffn
-
address@hidden {C Function} SCM scm_spawn_thread (scm_t_catch_body body, void 
*body_data, scm_t_catch_handler handler, void *handler_data)
-Call @var{body} in a new thread, passing it @var{body_data}, returning
-the new thread.  The function @var{body} is called via
address@hidden
-
-When @var{handler} is address@hidden, @var{body} is called via
address@hidden with tag @code{SCM_BOOL_T} that has
address@hidden and @var{handler_data} as the handler and its data.  This
-catch is established inside the continuation barrier.
-
-Once @var{body} or @var{handler} returns, the return value is made the
address@hidden value} of the thread and the thread is terminated.
address@hidden deftypefn
-
address@hidden {Scheme Procedure} thread? obj
address@hidden {C Function} scm_thread_p (obj)
-Return @code{#t} ff @var{obj} is a thread; otherwise, return
address@hidden
address@hidden deffn
-
address@hidden begin (texi-doc-string "guile" "join-thread")
address@hidden {Scheme Procedure} join-thread thread [timeout [timeoutval]]
address@hidden {C Function} scm_join_thread (thread)
address@hidden {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
-specified; @code{#f} is returned otherwise).
address@hidden deffn
-
address@hidden {Scheme Procedure} thread-exited? thread
address@hidden {C Function} scm_thread_exited_p (thread)
-Return @code{#t} if @var{thread} has exited, or @code{#f} otherwise.
address@hidden deffn
-
address@hidden begin (texi-doc-string "guile" "yield")
address@hidden {Scheme Procedure} yield
-If one or more threads are waiting to execute, calling yield forces an
-immediate context switch to one of them. Otherwise, yield has no effect.
address@hidden deffn
-
address@hidden {Scheme Procedure} cancel-thread thread
address@hidden {C Function} scm_cancel_thread (thread)
-Asynchronously notify @var{thread} to exit.  Immediately after
-receiving this notification, @var{thread} will call its cleanup handler
-(if one has been set) and then terminate, aborting any evaluation that
-is in progress.
-
-Because Guile threads are isomorphic with POSIX threads, @var{thread}
-will not receive its cancellation signal until it reaches a cancellation
-point.  See your operating system's POSIX threading documentation for
-more information on cancellation points; note that in Guile, unlike
-native POSIX threads, a thread can receive a cancellation notification
-while attempting to lock a mutex.
address@hidden deffn
-
address@hidden {Scheme Procedure} set-thread-cleanup! thread proc
address@hidden {C Function} scm_set_thread_cleanup_x (thread, proc)
-Set @var{proc} as the cleanup handler for the thread @var{thread}.
address@hidden, which must be a thunk, will be called when @var{thread}
-exits, either normally or by being canceled.  Thread cleanup handlers
-can be used to perform useful tasks like releasing resources, such as
-locked mutexes, when thread exit cannot be predicted.
-
-The return value of @var{proc} will be set as the @emph{exit value} of
address@hidden
-
-To remove a cleanup handler, pass @code{#f} for @var{proc}.
address@hidden deffn
-
address@hidden {Scheme Procedure} thread-cleanup thread
address@hidden {C Function} scm_thread_cleanup (thread)
-Return the cleanup handler currently installed for the thread
address@hidden  If no cleanup handler is currently installed,
-thread-cleanup returns @code{#f}.
address@hidden deffn
-
-Higher level thread procedures are available by loading the
address@hidden(ice-9 threads)} module.  These provide standardized
-thread creation.
-
address@hidden macro make-thread proc arg @dots{}
-Apply @var{proc} to @var{arg} @dots{} in a new thread formed by
address@hidden using a default error handler that display
-the error to the current error port.  The @var{arg} @dots{}
-expressions are evaluated in the new thread.
address@hidden deffn
-
address@hidden macro begin-thread expr1 expr2 @dots{}
-Evaluate forms @var{expr1} @var{expr2} @dots{} in a new thread formed by
address@hidden using a default error handler that display
-the error to the current error port.
address@hidden deffn
-
 @node Mutexes and Condition Variables
 @subsection Mutexes and Condition Variables
 @cindex mutex