176 lines
11 KiB
HTML
176 lines
11 KiB
HTML
|
<!DOCTYPE html>
|
||
|
|
<html>
|
||
|
|
<!-- Created by GNU Texinfo 7.1, https://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<!-- This manual documents Guile version 3.0.10.
|
||
|
|
|
||
|
|
Copyright (C) 1996-1997, 2000-2005, 2009-2023 Free Software Foundation,
|
||
|
|
Inc.
|
||
|
|
|
||
|
|
Copyright (C) 2021 Maxime Devos
|
||
|
|
|
||
|
|
Copyright (C) 2024 Tomas Volf
|
||
|
|
|
||
|
|
|
||
|
|
Permission is granted to copy, distribute and/or modify this document
|
||
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
|
|
any later version published by the Free Software Foundation; with no
|
||
|
|
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
|
||
|
|
copy of the license is included in the section entitled "GNU Free
|
||
|
|
Documentation License." -->
|
||
|
|
<title>SRFI-18 Threads (Guile Reference Manual)</title>
|
||
|
|
|
||
|
|
<meta name="description" content="SRFI-18 Threads (Guile Reference Manual)">
|
||
|
|
<meta name="keywords" content="SRFI-18 Threads (Guile Reference Manual)">
|
||
|
|
<meta name="resource-type" content="document">
|
||
|
|
<meta name="distribution" content="global">
|
||
|
|
<meta name="Generator" content=".texi2any-real">
|
||
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||
|
|
|
||
|
|
<link href="index.html" rel="start" title="Top">
|
||
|
|
<link href="Concept-Index.html" rel="index" title="Concept Index">
|
||
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||
|
|
<link href="SRFI_002d18.html" rel="up" title="SRFI-18">
|
||
|
|
<link href="SRFI_002d18-Mutexes.html" rel="next" title="SRFI-18 Mutexes">
|
||
|
|
<style type="text/css">
|
||
|
|
<!--
|
||
|
|
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
|
||
|
|
span:hover a.copiable-link {visibility: visible}
|
||
|
|
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
<link rel="stylesheet" type="text/css" href="https://www.gnu.org/software/gnulib/manual.css">
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en">
|
||
|
|
<div class="subsubsection-level-extent" id="SRFI_002d18-Threads">
|
||
|
|
<div class="nav-panel">
|
||
|
|
<p>
|
||
|
|
Next: <a href="SRFI_002d18-Mutexes.html" accesskey="n" rel="next">SRFI-18 Mutexes</a>, Up: <a href="SRFI_002d18.html" accesskey="u" rel="up">SRFI-18 - Multithreading support</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<h4 class="subsubsection" id="SRFI_002d18-Threads-1"><span>7.5.15.1 SRFI-18 Threads<a class="copiable-link" href="#SRFI_002d18-Threads-1"> ¶</a></span></h4>
|
||
|
|
|
||
|
|
<p>Threads created by SRFI-18 differ in two ways from threads created by
|
||
|
|
Guile’s built-in thread functions. First, a thread created by SRFI-18
|
||
|
|
<code class="code">make-thread</code> begins in a blocked state and will not start
|
||
|
|
execution until <code class="code">thread-start!</code> is called on it. Second, SRFI-18
|
||
|
|
threads are constructed with a top-level exception handler that
|
||
|
|
captures any exceptions that are thrown on thread exit.
|
||
|
|
</p>
|
||
|
|
<p>SRFI-18 threads are disjoint from Guile’s primitive threads.
|
||
|
|
See <a class="xref" href="Threads.html">Threads</a>, for more on Guile’s primitive facility.
|
||
|
|
</p>
|
||
|
|
<dl class="first-deffn first-defun-alias-first-deffn">
|
||
|
|
<dt class="deffn defun-alias-deffn" id="index-current_002dthread-1"><span class="category-def">Function: </span><span><strong class="def-name">current-thread</strong><a class="copiable-link" href="#index-current_002dthread-1"> ¶</a></span></dt>
|
||
|
|
<dd><p>Returns the thread that called this function. This is the same
|
||
|
|
procedure as the same-named built-in procedure <code class="code">current-thread</code>
|
||
|
|
(see <a class="pxref" href="Threads.html">Threads</a>).
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn first-defun-alias-first-deffn">
|
||
|
|
<dt class="deffn defun-alias-deffn" id="index-thread_003f-1"><span class="category-def">Function: </span><span><strong class="def-name">thread?</strong> <var class="def-var-arguments">obj</var><a class="copiable-link" href="#index-thread_003f-1"> ¶</a></span></dt>
|
||
|
|
<dd><p>Returns <code class="code">#t</code> if <var class="var">obj</var> is a thread, <code class="code">#f</code> otherwise. This
|
||
|
|
is the same procedure as the same-named built-in procedure
|
||
|
|
<code class="code">thread?</code> (see <a class="pxref" href="Threads.html">Threads</a>).
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn first-defun-alias-first-deffn">
|
||
|
|
<dt class="deffn defun-alias-deffn" id="index-make_002dthread-1"><span class="category-def">Function: </span><span><strong class="def-name">make-thread</strong> <var class="def-var-arguments">thunk [name]</var><a class="copiable-link" href="#index-make_002dthread-1"> ¶</a></span></dt>
|
||
|
|
<dd><p>Call <code class="code">thunk</code> in a new thread and with a new dynamic state,
|
||
|
|
returning the new thread and optionally assigning it the object name
|
||
|
|
<var class="var">name</var>, which may be any Scheme object.
|
||
|
|
</p>
|
||
|
|
<p>Note that the name <code class="code">make-thread</code> conflicts with the
|
||
|
|
<code class="code">(ice-9 threads)</code> function <code class="code">make-thread</code>. Applications
|
||
|
|
wanting to use both of these functions will need to refer to them by
|
||
|
|
different names.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn first-defun-alias-first-deffn">
|
||
|
|
<dt class="deffn defun-alias-deffn" id="index-thread_002dname"><span class="category-def">Function: </span><span><strong class="def-name">thread-name</strong> <var class="def-var-arguments">thread</var><a class="copiable-link" href="#index-thread_002dname"> ¶</a></span></dt>
|
||
|
|
<dd><p>Returns the name assigned to <var class="var">thread</var> at the time of its creation,
|
||
|
|
or <code class="code">#f</code> if it was not given a name.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn first-defun-alias-first-deffn">
|
||
|
|
<dt class="deffn defun-alias-deffn" id="index-thread_002dspecific"><span class="category-def">Function: </span><span><strong class="def-name">thread-specific</strong> <var class="def-var-arguments">thread</var><a class="copiable-link" href="#index-thread_002dspecific"> ¶</a></span></dt>
|
||
|
|
<dt class="deffnx defunx-alias-deffnx def-cmd-deffn" id="index-thread_002dspecific_002dset_0021"><span class="category-def">Function: </span><span><strong class="def-name">thread-specific-set!</strong> <var class="def-var-arguments">thread obj</var><a class="copiable-link" href="#index-thread_002dspecific_002dset_0021"> ¶</a></span></dt>
|
||
|
|
<dd><p>Get or set the “object-specific” property of <var class="var">thread</var>. In
|
||
|
|
Guile’s implementation of SRFI-18, this value is stored as an object
|
||
|
|
property, and will be <code class="code">#f</code> if not set.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn first-defun-alias-first-deffn">
|
||
|
|
<dt class="deffn defun-alias-deffn" id="index-thread_002dstart_0021"><span class="category-def">Function: </span><span><strong class="def-name">thread-start!</strong> <var class="def-var-arguments">thread</var><a class="copiable-link" href="#index-thread_002dstart_0021"> ¶</a></span></dt>
|
||
|
|
<dd><p>Unblocks <var class="var">thread</var> and allows it to begin execution if it has not
|
||
|
|
done so already.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn first-defun-alias-first-deffn">
|
||
|
|
<dt class="deffn defun-alias-deffn" id="index-thread_002dyield_0021"><span class="category-def">Function: </span><span><strong class="def-name">thread-yield!</strong><a class="copiable-link" href="#index-thread_002dyield_0021"> ¶</a></span></dt>
|
||
|
|
<dd><p>If one or more threads are waiting to execute, calling
|
||
|
|
<code class="code">thread-yield!</code> forces an immediate context switch to one of them.
|
||
|
|
Otherwise, <code class="code">thread-yield!</code> has no effect. <code class="code">thread-yield!</code>
|
||
|
|
behaves identically to the Guile built-in function <code class="code">yield</code>.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn first-defun-alias-first-deffn">
|
||
|
|
<dt class="deffn defun-alias-deffn" id="index-thread_002dsleep_0021"><span class="category-def">Function: </span><span><strong class="def-name">thread-sleep!</strong> <var class="def-var-arguments">timeout</var><a class="copiable-link" href="#index-thread_002dsleep_0021"> ¶</a></span></dt>
|
||
|
|
<dd><p>The current thread waits until the point specified by the time object
|
||
|
|
<var class="var">timeout</var> is reached (see <a class="pxref" href="SRFI_002d18-Time.html">SRFI-18 Time</a>). This blocks the
|
||
|
|
thread only if <var class="var">timeout</var> represents a point in the future. it is
|
||
|
|
an error for <var class="var">timeout</var> to be <code class="code">#f</code>.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn first-defun-alias-first-deffn">
|
||
|
|
<dt class="deffn defun-alias-deffn" id="index-thread_002dterminate_0021"><span class="category-def">Function: </span><span><strong class="def-name">thread-terminate!</strong> <var class="def-var-arguments">thread</var><a class="copiable-link" href="#index-thread_002dterminate_0021"> ¶</a></span></dt>
|
||
|
|
<dd><p>Causes an abnormal termination of <var class="var">thread</var>. If <var class="var">thread</var> is
|
||
|
|
not already terminated, all mutexes owned by <var class="var">thread</var> become
|
||
|
|
unlocked/abandoned. If <var class="var">thread</var> is the current thread,
|
||
|
|
<code class="code">thread-terminate!</code> does not return. Otherwise
|
||
|
|
<code class="code">thread-terminate!</code> returns an unspecified value; the termination
|
||
|
|
of <var class="var">thread</var> will occur before <code class="code">thread-terminate!</code> returns.
|
||
|
|
Subsequent attempts to join on <var class="var">thread</var> will cause a “terminated
|
||
|
|
thread exception” to be raised.
|
||
|
|
</p>
|
||
|
|
<p><code class="code">thread-terminate!</code> is compatible with the thread cancellation
|
||
|
|
procedures in the core threads API (see <a class="pxref" href="Threads.html">Threads</a>) in that if a
|
||
|
|
cleanup handler has been installed for the target thread, it will be
|
||
|
|
called before the thread exits and its return value (or exception, if
|
||
|
|
any) will be stored for later retrieval via a call to
|
||
|
|
<code class="code">thread-join!</code>.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn first-defun-alias-first-deffn">
|
||
|
|
<dt class="deffn defun-alias-deffn" id="index-thread_002djoin_0021"><span class="category-def">Function: </span><span><strong class="def-name">thread-join!</strong> <var class="def-var-arguments">thread [timeout [timeout-val]]</var><a class="copiable-link" href="#index-thread_002djoin_0021"> ¶</a></span></dt>
|
||
|
|
<dd><p>Wait for <var class="var">thread</var> to terminate and return its exit value. When a
|
||
|
|
time value <var class="var">timeout</var> is given, it specifies a point in time where
|
||
|
|
the waiting should be aborted. When the waiting is aborted,
|
||
|
|
<var class="var">timeout-val</var> is returned if it is specified; otherwise, a
|
||
|
|
<code class="code">join-timeout-exception</code> exception is raised
|
||
|
|
(see <a class="pxref" href="SRFI_002d18-Exceptions.html">SRFI-18 Exceptions</a>). Exceptions may also be raised if the
|
||
|
|
thread was terminated by a call to <code class="code">thread-terminate!</code>
|
||
|
|
(<code class="code">terminated-thread-exception</code> will be raised) or if the thread
|
||
|
|
exited by raising an exception that was handled by the top-level
|
||
|
|
exception handler (<code class="code">uncaught-exception</code> will be raised; the
|
||
|
|
original exception can be retrieved using
|
||
|
|
<code class="code">uncaught-exception-reason</code>).
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<div class="nav-panel">
|
||
|
|
<p>
|
||
|
|
Next: <a href="SRFI_002d18-Mutexes.html">SRFI-18 Mutexes</a>, Up: <a href="SRFI_002d18.html">SRFI-18 - Multithreading support</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|