/usr/lib/swi-prolog/doc/Manual/thutil.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<html>
<head>
<title>SWI-Prolog 7.1.16 Reference Manual: Section 8.5</title><link rel="home" href="index.html">
<link rel="contents" href="Contents.html">
<link rel="index" href="DocIndex.html">
<link rel="summary" href="summary.html">
<link rel="previous" href="threadsync.html">
<link rel="next" href="foreignthread.html">

<style type="text/css">

/* Style sheet for SWI-Prolog latex2html
*/

dd.defbody
{ margin-bottom: 1em;
}

dt.pubdef, dt.multidef
{ color: #fff;
padding: 2px 10px 0px 10px;
margin-bottom: 5px;
font-size: 18px;
vertical-align: middle;
overflow: hidden;
}

dt.pubdef { background-color: #0c3d6e; }
dt.multidef { background-color: #ef9439; }

.bib dd
{ margin-bottom: 1em;
}

.bib dt
{ float: left;
margin-right: 1.3ex;
}

pre.code
{ margin-left: 1.5em;
margin-right: 1.5em;
border: 1px dotted;
padding-top: 5px;
padding-left: 5px;
padding-bottom: 5px;
background-color: #f8f8f8;
}

div.navigate
{ text-align: center;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
}

div.title
{ text-align: center;
padding-bottom: 1em;
font-size: 200%;
font-weight: bold;
}

div.author
{ text-align: center;
font-style: italic;
}

div.abstract
{ margin-top: 2em;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
margin-left: 10%; margin-right:10%;
}

div.abstract-title
{ text-align: center;
padding: 5px;
font-size: 120%;
font-weight: bold;
}

div.toc-h1
{ font-size: 200%;
font-weight: bold;
}

div.toc-h2
{ font-size: 120%;
font-weight: bold;
margin-left: 2em;
}

div.toc-h3
{ font-size: 100%;
font-weight: bold;
margin-left: 4em;
}

div.toc-h4
{ font-size: 100%;
margin-left: 6em;
}

span.sec-nr
{
}

span.sec-title
{
}

span.pred-ext
{ font-weight: bold;
}

span.pred-tag
{ float: right;
padding-top: 0.2em;
font-size: 80%;
font-style: italic;
color: #fff;
}

div.caption
{ width: 80%;
margin: auto;
text-align:center;
}

/* Footnotes */
.fn {
color: red;
font-size: 70%;
}

.fn-text, .fnp {
position: absolute;
top: auto;
left: 10%;
border: 1px solid #000;
box-shadow: 5px 5px 5px #888;
display: none;
background: #fff;
color: #000;
margin-top: 25px;
padding: 8px 12px;
font-size: larger;
}

sup:hover span.fn-text
{ display: block;
}

/* Lists */

dl.latex
{ margin-top: 1ex;
margin-bottom: 0.5ex;
}

dl.latex dl.latex dd.defbody
{ margin-bottom: 0.5ex;
}

/* PlDoc Tags */

dl.tags
{ font-size: 90%;
margin-left: 5ex;
margin-top: 1ex;
margin-bottom: 0.5ex;
}

dl.tags dt
{ margin-left: 0pt;
font-weight: bold;
}

dl.tags dd
{ margin-left: 3ex;
}

td.param
{ font-style: italic;
font-weight: bold;
}

/* Index */

dt.index-sep
{ font-weight: bold;
font-size: +1;
margin-top: 1ex;
}

/* Tables */

table.center
{ margin: auto;
}

table.latex
{ border-collapse:collapse;
}

table.latex tr
{ vertical-align: text-top;
}

table.latex td,th
{ padding: 2px 1em;
}

table.latex tr.hline td,th
{ border-top: 1px solid black;
}

table.frame-box
{ border: 2px solid black;
}

</style>
</head>
<body style="background:white">
<div class="navigate"><a class="nav" href="index.html"><img src="home.gif" alt="Home"></a>
<a class="nav" href="Contents.html"><img src="index.gif" alt="Contents"></a>
<a class="nav" href="DocIndex.html"><img src="yellow_pages.gif" alt="Index"></a>
<a class="nav" href="summary.html"><img src="info.gif" alt="Summary"></a>
<a class="nav" href="threadsync.html"><img src="prev.gif" alt="Previous"></a>
<a class="nav" href="foreignthread.html"><img src="next.gif" alt="Next"></a>
</div>
<h2 id="sec:thutil"><a id="sec:8.5"><span class="sec-nr">8.5</span> <span class="sec-title">Thread 
support library(threadutil)</span></a></h2>

<a id="sec:thutil"></a>

<p>This library defines a couple of useful predicates for demonstrating 
and debugging multithreaded applications. This library is certainly not 
complete.

<dl class="latex">
<dt class="pubdef"><a id="threads/0"><strong>threads</strong></a></dt>
<dd class="defbody">
Lists all current threads and their status.</dd>
<dt class="pubdef"><a id="join_threads/0"><strong>join_threads</strong></a></dt>
<dd class="defbody">
Join all terminated threads. For normal applications, dealing with 
terminated threads must be part of the application logic, either 
detaching the thread before termination or making sure it will be 
joined. The predicate <a id="idx:jointhreads0:1650"></a><a class="pred" href="thutil.html#join_threads/0">join_threads/0</a> 
is intended for interactive sessions to reclaim resources from threads 
that died unexpectedly during development.</dd>
<dt class="pubdef"><a id="interactor/0"><strong>interactor</strong></a></dt>
<dd class="defbody">
Create a new console and run the Prolog top level in this new console. 
See also <a id="idx:attachconsole0:1651"></a><a class="pred" href="thutil.html#attach_console/0">attach_console/0</a>. 
In the Windows version a new interactor can also be created from the <b>Run/New 
thread</b> menu.
</dd>
</dl>

<p><h3 id="sec:threaddebug"><a id="sec:8.5.1"><span class="sec-nr">8.5.1</span> <span class="sec-title">Debugging 
threads</span></a></h3>

<a id="sec:threaddebug"></a>

<p>Support for debugging threads is still very limited. Debug and trace 
mode are flags that are local to each thread. Individual threads can be 
debugged either using the graphical debugger described in
<a class="sec" href="guitracer.html">section 3.5</a> (see <a id="idx:tspy1:1652"></a><a class="pred" href="thutil.html#tspy/1">tspy/1</a> 
and friends) or by attaching a console to the thread and running the 
traditional command line debugger (see
<a id="idx:attachconsole0:1653"></a><a class="pred" href="thutil.html#attach_console/0">attach_console/0</a>). 
When using the graphical debugger, the debugger must be <em>loaded</em> 
from the main thread (for example using guitracer) before <a id="idx:gtrace0:1654"></a><a class="pred" href="guitracer.html#gtrace/0">gtrace/0</a> 
can be called from a thread.

<dl class="latex">
<dt class="pubdef"><a id="attach_console/0"><strong>attach_console</strong></a></dt>
<dd class="defbody">
If the current thread has no console attached yet, attach one and 
redirect the user streams (input, output, and error) to the new console 
window. On Unix systems the console is an <b>xterm</b> application. On 
Windows systems this requires the GUI version <b>swipl-win.exe</b> 
rather than the console-based <b>swipl.exe</b>.

<p>This predicate has a couple of useful applications. One is to 
separate (debugging) I/O of different threads. Another is to start 
debugging a thread that is running in the background. If thread 10 is 
running, the following sequence starts the tracer on this thread:

<pre class="code">
?- thread_signal(10, (attach_console, trace)).
</pre>

</dd>
<dt class="pubdef"><a id="tdebug/1"><strong>tdebug</strong>(<var>+ThreadId</var>)</a></dt>
<dd class="defbody">
Prepare <var>ThreadId</var> for debugging using the graphical tracer. 
This implies installing the tracer hooks in the thread and switching the 
thread to debug mode using <a id="idx:debug0:1655"></a><a class="pred" href="debugger.html#debug/0">debug/0</a>. 
The call is injected into the thread using <a id="idx:threadsignal2:1656"></a><a class="pred" href="threadcom.html#thread_signal/2">thread_signal/2</a>. 
We refer to the documentation of this predicate for asynchronous 
interaction with threads. New threads created inherit their debug mode 
from the thread that created them.</dd>
<dt class="pubdef"><a id="tdebug/0"><strong>tdebug</strong></a></dt>
<dd class="defbody">
Call <a id="idx:tdebug1:1657"></a><a class="pred" href="thutil.html#tdebug/1">tdebug/1</a> 
in all running threads.</dd>
<dt class="pubdef"><a id="tnodebug/1"><strong>tnodebug</strong>(<var>+ThreadId</var>)</a></dt>
<dd class="defbody">
Disable debugging thread <var>ThreadId</var>.</dd>
<dt class="pubdef"><a id="tnodebug/0"><strong>tnodebug</strong></a></dt>
<dd class="defbody">
Disable debugging in all threads.</dd>
<dt class="pubdef"><a id="tspy/2"><strong>tspy</strong>(<var>:Spec, 
+ThreadId</var>)</a></dt>
<dd class="defbody">
Set a spy point as <a id="idx:spy1:1658"></a><a class="pred" href="debugger.html#spy/1">spy/1</a> 
and enable the thread for debugging using
<a id="idx:tdebug1:1659"></a><a class="pred" href="thutil.html#tdebug/1">tdebug/1</a>. 
Note that a spy point is a global flag on a predicate that is visible 
from all threads. Spy points are honoured in all threads that are in 
debug mode and ignored in threads that are in nodebug mode.</dd>
<dt class="pubdef"><a id="tspy/1"><strong>tspy</strong>(<var>:Spec</var>)</a></dt>
<dd class="defbody">
Set a spy point as <a id="idx:spy1:1660"></a><a class="pred" href="debugger.html#spy/1">spy/1</a> 
and enable debugging in all threads using
<a id="idx:tdebug0:1661"></a><a class="pred" href="thutil.html#tdebug/0">tdebug/0</a>. 
Note that removing spy points can be done using <a id="idx:nospy1:1662"></a><a class="pred" href="debugger.html#nospy/1">nospy/1</a>. 
Disabling spy points in a specific thread is achieved by <a id="idx:tnodebug1:1663"></a><a class="pred" href="thutil.html#tnodebug/1">tnodebug/1</a>.
</dd>
</dl>

<p><h3 id="sec:tprofile"><a id="sec:8.5.2"><span class="sec-nr">8.5.2</span> <span class="sec-title">Profiling 
threads</span></a></h3>

<a id="sec:tprofile"></a>

<p>In the current implementation, at most one thread can be profiled at 
any moment. Any thread can call <a id="idx:profile1:1664"></a><a class="pred" href="profile.html#profile/1">profile/1</a> 
to profile the execution of some part of its code. The predicate <a id="idx:tprofile1:1665"></a><a class="pred" href="thutil.html#tprofile/1">tprofile/1</a> 
allows for profiling the execution of another thread until the user 
stops collecting profile data.

<dl class="latex">
<dt class="pubdef"><a id="tprofile/1"><strong>tprofile</strong>(<var>+ThreadId</var>)</a></dt>
<dd class="defbody">
Start collecting profile data in <var>ThreadId</var> and ask the user to 
hit
&lt;<var>return</var>&gt; to stop the profiler. See <a class="sec" href="profile.html">section 
4.40</a> for details on the execution profiler.
</dd>
</dl>

<p></body></html>
swi-prolog-nox 6.6.6-5 / usr / lib / swi-prolog / doc / Manual / thutil.html
