mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-04-30 03:40:34 +02:00
Small api-scheduling.texi reorder
* doc/ref/api-scheduling.texi: Put "Threads" section at beginning of scheduling chapter.
This commit is contained in:
Andy Wingo
parent
51d322b2d4
commit
efcc30fc34
1 changed files with 140 additions and 139 deletions
|
|
@ -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
|
||||
|
||||
|
||||
@node Threads
|
||||
@subsection Threads
|
||||
@cindex threads
|
||||
@cindex Guile threads
|
||||
@cindex POSIX threads
|
||||
|
||||
Guile supports POSIX threads, unless it was configured with
|
||||
@code{--without-threads} 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}).
|
||||
|
||||
@deffn {Scheme Procedure} all-threads
|
||||
@deffnx {C Function} scm_all_threads ()
|
||||
Return a list of all threads.
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} current-thread
|
||||
@deffnx {C Function} scm_current_thread ()
|
||||
Return the thread that called this function.
|
||||
@end deffn
|
||||
|
||||
@c begin (texi-doc-string "guile" "call-with-new-thread")
|
||||
@deffn {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
|
||||
@code{with-continuation-barrier}.
|
||||
|
||||
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.
|
||||
@end deffn
|
||||
|
||||
@deftypefn {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
|
||||
@code{scm_c_with_continuation_barrier}.
|
||||
|
||||
When @var{handler} is non-@code{NULL}, @var{body} is called via
|
||||
@code{scm_internal_catch} with tag @code{SCM_BOOL_T} that has
|
||||
@var{handler} 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
|
||||
@emph{exit value} of the thread and the thread is terminated.
|
||||
@end deftypefn
|
||||
|
||||
@deffn {Scheme Procedure} thread? obj
|
||||
@deffnx {C Function} scm_thread_p (obj)
|
||||
Return @code{#t} ff @var{obj} is a thread; otherwise, return
|
||||
@code{#f}.
|
||||
@end deffn
|
||||
|
||||
@c begin (texi-doc-string "guile" "join-thread")
|
||||
@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
|
||||
@code{scm_spawn_thread} have an exit value of @code{#f}. 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
|
||||
@code{current-time} 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
|
||||
|
||||
@deffn {Scheme Procedure} thread-exited? thread
|
||||
@deffnx {C Function} scm_thread_exited_p (thread)
|
||||
Return @code{#t} if @var{thread} has exited, or @code{#f} otherwise.
|
||||
@end deffn
|
||||
|
||||
@c begin (texi-doc-string "guile" "yield")
|
||||
@deffn {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.
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} cancel-thread thread
|
||||
@deffnx {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.
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} set-thread-cleanup! thread proc
|
||||
@deffnx {C Function} scm_set_thread_cleanup_x (thread, proc)
|
||||
Set @var{proc} as the cleanup handler for the thread @var{thread}.
|
||||
@var{proc}, 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
|
||||
@var{thread}.
|
||||
|
||||
To remove a cleanup handler, pass @code{#f} for @var{proc}.
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} thread-cleanup thread
|
||||
@deffnx {C Function} scm_thread_cleanup (thread)
|
||||
Return the cleanup handler currently installed for the thread
|
||||
@var{thread}. If no cleanup handler is currently installed,
|
||||
thread-cleanup returns @code{#f}.
|
||||
@end deffn
|
||||
|
||||
Higher level thread procedures are available by loading the
|
||||
@code{(ice-9 threads)} module. These provide standardized
|
||||
thread creation.
|
||||
|
||||
@deffn macro make-thread proc arg @dots{}
|
||||
Apply @var{proc} to @var{arg} @dots{} in a new thread formed by
|
||||
@code{call-with-new-thread} 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.
|
||||
@end deffn
|
||||
|
||||
@deffn macro begin-thread expr1 expr2 @dots{}
|
||||
Evaluate forms @var{expr1} @var{expr2} @dots{} in a new thread formed by
|
||||
@code{call-with-new-thread} using a default error handler that display
|
||||
the error to the current error port.
|
||||
@end deffn
|
||||
|
||||
|
||||
@node Asyncs
|
||||
@subsection Asynchronous Interrupts
|
||||
|
||||
|
|
@ -188,144 +327,6 @@ checking if the return value is @code{eq?} to @var{expected}.
|
|||
@end deffn
|
||||
|
||||
|
||||
@node Threads
|
||||
@subsection Threads
|
||||
@cindex threads
|
||||
@cindex Guile threads
|
||||
@cindex POSIX threads
|
||||
|
||||
Guile supports POSIX threads, unless it was configured with
|
||||
@code{--without-threads} 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}).
|
||||
|
||||
@deffn {Scheme Procedure} all-threads
|
||||
@deffnx {C Function} scm_all_threads ()
|
||||
Return a list of all threads.
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} current-thread
|
||||
@deffnx {C Function} scm_current_thread ()
|
||||
Return the thread that called this function.
|
||||
@end deffn
|
||||
|
||||
@c begin (texi-doc-string "guile" "call-with-new-thread")
|
||||
@deffn {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
|
||||
@code{with-continuation-barrier}.
|
||||
|
||||
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.
|
||||
@end deffn
|
||||
|
||||
@deftypefn {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
|
||||
@code{scm_c_with_continuation_barrier}.
|
||||
|
||||
When @var{handler} is non-@code{NULL}, @var{body} is called via
|
||||
@code{scm_internal_catch} with tag @code{SCM_BOOL_T} that has
|
||||
@var{handler} 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
|
||||
@emph{exit value} of the thread and the thread is terminated.
|
||||
@end deftypefn
|
||||
|
||||
@deffn {Scheme Procedure} thread? obj
|
||||
@deffnx {C Function} scm_thread_p (obj)
|
||||
Return @code{#t} ff @var{obj} is a thread; otherwise, return
|
||||
@code{#f}.
|
||||
@end deffn
|
||||
|
||||
@c begin (texi-doc-string "guile" "join-thread")
|
||||
@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
|
||||
@code{scm_spawn_thread} have an exit value of @code{#f}. 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
|
||||
@code{current-time} 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
|
||||
|
||||
@deffn {Scheme Procedure} thread-exited? thread
|
||||
@deffnx {C Function} scm_thread_exited_p (thread)
|
||||
Return @code{#t} if @var{thread} has exited, or @code{#f} otherwise.
|
||||
@end deffn
|
||||
|
||||
@c begin (texi-doc-string "guile" "yield")
|
||||
@deffn {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.
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} cancel-thread thread
|
||||
@deffnx {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.
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} set-thread-cleanup! thread proc
|
||||
@deffnx {C Function} scm_set_thread_cleanup_x (thread, proc)
|
||||
Set @var{proc} as the cleanup handler for the thread @var{thread}.
|
||||
@var{proc}, 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
|
||||
@var{thread}.
|
||||
|
||||
To remove a cleanup handler, pass @code{#f} for @var{proc}.
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} thread-cleanup thread
|
||||
@deffnx {C Function} scm_thread_cleanup (thread)
|
||||
Return the cleanup handler currently installed for the thread
|
||||
@var{thread}. If no cleanup handler is currently installed,
|
||||
thread-cleanup returns @code{#f}.
|
||||
@end deffn
|
||||
|
||||
Higher level thread procedures are available by loading the
|
||||
@code{(ice-9 threads)} module. These provide standardized
|
||||
thread creation.
|
||||
|
||||
@deffn macro make-thread proc arg @dots{}
|
||||
Apply @var{proc} to @var{arg} @dots{} in a new thread formed by
|
||||
@code{call-with-new-thread} 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.
|
||||
@end deffn
|
||||
|
||||
@deffn macro begin-thread expr1 expr2 @dots{}
|
||||
Evaluate forms @var{expr1} @var{expr2} @dots{} in a new thread formed by
|
||||
@code{call-with-new-thread} using a default error handler that display
|
||||
the error to the current error port.
|
||||
@end deffn
|
||||
|
||||
@node Mutexes and Condition Variables
|
||||
@subsection Mutexes and Condition Variables
|
||||
@cindex mutex
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue