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

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

<HTML>
<HEAD>
<TITLE>SWI-Prolog 5.11.18 Reference Manual: Section 8.1</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="threads.html">
<LINK REL=next HREF="thmonitor.html">
<STYLE type="text/css">
/* Style sheet for SWI-Prolog latex2html
*/

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

dt.pubdef
{ background-color: #c5e1ff;
}

dt.multidef
{ background-color: #c8ffc7;
}

.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: #202020;
}

/* Footnotes */

sup.fn { color: blue; text-decoration: underline; }
span.fn-text { display: none; }
sup.fn span {display: none;}
sup:hover span
{ display: block !important;
position: absolute; top: auto; left: auto; width: 80%;
color: #000; background: white;
border: 2px solid;
padding: 5px; margin: 10px; z-index: 100;
font-size: smaller;
}
</STYLE>
</HEAD>
<BODY BGCOLOR="white">
<DIV class="navigate"><A class="nav" href="index.html"><IMG SRC="home.gif" BORDER=0 ALT="Home"></A>
<A class="nav" href="Contents.html"><IMG SRC="index.gif" BORDER=0 ALT="Contents"></A>
<A class="nav" href="DocIndex.html"><IMG SRC="yellow_pages.gif" BORDER=0 ALT="Index"></A>
<A class="nav" href="summary.html"><IMG SRC="info.gif" BORDER=0 ALT="Summary"></A>
<A class="nav" href="threads.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A>
<A class="nav" href="thmonitor.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A>
</DIV>

<H2><A NAME="sec:8.1"><SPAN class="sec-nr">8.1</SPAN> <SPAN class="sec-title">Creating 
and destroying Prolog threads</SPAN></A></H2>

<A NAME="sec:threadcreate"></A>

<DL class="latex">
<DT class="pubdef"><A NAME="thread_create/3"><STRONG>thread_create</STRONG>(<VAR>:Goal, 
-Id, +Options</VAR>)</A></DT>
<DD class="defbody">
Create a new Prolog thread (and underlying C-thread) and start it by 
executing <VAR>Goal</VAR>. If the thread is created successfully, the 
thread-identifier of the created thread is unified to <VAR>Id</VAR>.
<VAR>Options</VAR> is a list of options. The currently defined options 
are below. Stack size options can also take the value <CODE>inf</CODE> 
or
<CODE>infinite</CODE>, which is mapped to the maximum stack size 
supported by the platform.

<DL class="latex">
<DT><STRONG>alias</STRONG>(<VAR>AliasName</VAR>)</DT>
<DD class="defbody">
Associate an `alias-name' with the thread. This named may be used to 
refer to the thread and remains valid until the thread is joined (see <A NAME="idx:threadjoin2:1365"></A><A class="pred" href="threadcreate.html#thread_join/2">thread_join/2</A>).</DD>
<DT><STRONG>at_exit</STRONG>(<VAR>:AtExit</VAR>)</DT>
<DD class="defbody">
Register <VAR>AtExit</VAR> as using <A NAME="idx:threadatexit1:1366"></A><A class="pred" href="threadcreate.html#thread_at_exit/1">thread_at_exit/1</A> 
before entering the thread goal. Unlike calling <A NAME="idx:threadatexit1:1367"></A><A class="pred" href="threadcreate.html#thread_at_exit/1">thread_at_exit/1</A> 
as part of the normal
<VAR>Goal</VAR>, this <EM>ensures</EM> the <VAR>Goal</VAR> is called. 
Using
<A NAME="idx:threadatexit1:1368"></A><A class="pred" href="threadcreate.html#thread_at_exit/1">thread_at_exit/1</A>, 
the thread may be signalled or run out of resources before <A NAME="idx:threadatexit1:1369"></A><A class="pred" href="threadcreate.html#thread_at_exit/1">thread_at_exit/1</A> 
is reached.</DD>
<DT><STRONG>detached</STRONG>(<VAR>Bool</VAR>)</DT>
<DD class="defbody">
If <CODE>false</CODE> (default), the thread can be waited for using
<A NAME="idx:threadjoin2:1370"></A><A class="pred" href="threadcreate.html#thread_join/2">thread_join/2</A>. <A NAME="idx:threadjoin2:1371"></A><A class="pred" href="threadcreate.html#thread_join/2">thread_join/2</A> 
must be called on this thread to reclaim all resources associated with 
the thread. If <CODE>true</CODE>, the system will reclaim all associated 
resources automatically after the thread finishes. Please note that 
thread identifiers are freed for reuse after a detached thread finishes 
or a normal thread has been joined. See also <A NAME="idx:threadjoin2:1372"></A><A class="pred" href="threadcreate.html#thread_join/2">thread_join/2</A> 
and <A NAME="idx:threaddetach1:1373"></A><A class="pred" href="threadcreate.html#thread_detach/1">thread_detach/1</A>.

<P>If a detached thread dies due to failure or exception of the initial 
goal the thread prints a message using <A NAME="idx:printmessage2:1374"></A><A class="pred" href="exception.html#print_message/2">print_message/2</A>. 
If such termination is considered normal, the code must be wrapped using
<A NAME="idx:ignore1:1375"></A><A class="pred" href="metacall.html#ignore/1">ignore/1</A> 
and/or <A NAME="idx:catch3:1376"></A><A class="pred" href="exception.html#catch/3">catch/3</A> 
to ensure successful completion.</DD>
<DT><STRONG>global</STRONG>(<VAR>K-Bytes</VAR>)</DT>
<DD class="defbody">
Set the limit to which the global stack of this thread may grow. If 
omitted, the limit of the calling thread is used. See also the
<STRONG>-G</STRONG> command-line option.</DD>
<DT><STRONG>local</STRONG>(<VAR>K-Bytes</VAR>)</DT>
<DD class="defbody">
Set the limit to which the local stack of this thread may grow. If 
omitted, the limit of the calling thread is used. See also the
<STRONG>-L</STRONG> command-line option.</DD>
<DT><STRONG>c_stack</STRONG>(<VAR>K-Bytes</VAR>)</DT>
<DD class="defbody">
Set the limit to which the system stack of this thread may grow. The 
default, minimum and maximum values are system-dependent.<SUP class="fn">82<SPAN class="fn-text">Older 
versions used <CODE>stack</CODE>. This is still accepted as a synonym.</SPAN></SUP>.</DD>
<DT><STRONG>trail</STRONG>(<VAR>K-Bytes</VAR>)</DT>
<DD class="defbody">
Set the limit to which the trail stack of this thread may grow. If 
omitted, the limit of the calling thread is used. See also the
<STRONG>-T</STRONG> command-line option.
</DD>
</DL>

<P>The <VAR>Goal</VAR> argument is <EM>copied</EM> to the new Prolog 
engine. This implies further instantiation of this term in either thread 
does not have consequences for the other thread: Prolog threads do not 
share data from their stacks.</DD>
<DT class="pubdef"><A NAME="thread_self/1"><STRONG>thread_self</STRONG>(<VAR>-Id</VAR>)</A></DT>
<DD class="defbody">
Get the Prolog thread identifier of the running thread. If the thread 
has an alias, the alias-name is returned.</DD>
<DT class="pubdef"><A NAME="thread_join/2"><STRONG>thread_join</STRONG>(<VAR>+Id, 
-Status</VAR>)</A></DT>
<DD class="defbody">
Wait for the termination of thread with given <VAR>Id</VAR>. Then unify 
the result-status of the thread with <VAR>Status</VAR>. After this call, <VAR>Id</VAR> 
becomes invalid and all resources associated with the thread are 
reclaimed. Note that threads with the attribute
<CODE>detached(true)</CODE> cannot be joined. See also <A NAME="idx:threadproperty2:1377"></A><A class="pred" href="thmonitor.html#thread_property/2">thread_property/2</A>.

<P>A thread that has been completed without <A NAME="idx:threadjoin2:1378"></A><A class="pred" href="threadcreate.html#thread_join/2">thread_join/2</A> 
being called on it is partly reclaimed: the Prolog stacks are released 
and the C-thread is destroyed. A small data-structure representing the 
exit-status of the thread is retained until <A NAME="idx:threadjoin2:1379"></A><A class="pred" href="threadcreate.html#thread_join/2">thread_join/2</A> 
is called on the thread. Defined values for <VAR>Status</VAR> are:

<DL class="latex">
<DT><STRONG>true</STRONG></DT>
<DD class="defbody">
The goal has been proven successfully.</DD>
<DT><STRONG>false</STRONG></DT>
<DD class="defbody">
The goal has failed.</DD>
<DT><STRONG>exception</STRONG>(<VAR>Term</VAR>)</DT>
<DD class="defbody">
The thread is terminated on an exception. See <A NAME="idx:printmessage2:1380"></A><A class="pred" href="exception.html#print_message/2">print_message/2</A> 
to turn system exceptions into readable messages.</DD>
<DT><STRONG>exited</STRONG>(<VAR>Term</VAR>)</DT>
<DD class="defbody">
The thread is terminated on <A NAME="idx:threadexit1:1381"></A><A class="pred" href="threadcreate.html#thread_exit/1">thread_exit/1</A> 
using the argument <VAR>Term</VAR>.
</DD>
</DL>

</DD>
<DT class="pubdef"><A NAME="thread_detach/1"><STRONG>thread_detach</STRONG>(<VAR>+Id</VAR>)</A></DT>
<DD class="defbody">
Switch thread into detached-state (see <CODE>detached(Bool)</CODE> 
option at
<A NAME="idx:threadcreate3:1382"></A><A class="pred" href="threadcreate.html#thread_create/3">thread_create/3</A>) 
at runtime. <VAR>Id</VAR> is the identifier of the thread placed in 
detached state. This may be the result of <A NAME="idx:threadself1:1383"></A><A class="pred" href="threadcreate.html#thread_self/1">thread_self/1</A>.

<P>One of the possible applications is to simplify debugging. Threads 
that are created as <EM>detached</EM> leave no traces if they crash. For 
not-detached threads the status can be inspected using
<A NAME="idx:threadproperty2:1384"></A><A class="pred" href="thmonitor.html#thread_property/2">thread_property/2</A>. 
Threads nobody is waiting for may be created normally and detach 
themselves just before completion. This way they leave no traces on 
normal completion and their reason for failure can be inspected.</DD>
<DT class="pubdef"><span class="pred-tag">[deprecated]</span><A NAME="thread_exit/1"><STRONG>thread_exit</STRONG>(<VAR>+Term</VAR>)</A></DT>
<DD class="defbody">
Terminates the thread immediately, leaving <CODE>exited(Term)</CODE> as 
result-state for <A NAME="idx:threadjoin2:1385"></A><A class="pred" href="threadcreate.html#thread_join/2">thread_join/2</A>. 
If the thread has the attribute
<CODE>detached(true)</CODE> it terminates, but its exit status cannot be 
retrieved using <A NAME="idx:threadjoin2:1386"></A><A class="pred" href="threadcreate.html#thread_join/2">thread_join/2</A> 
making the value of <VAR>Term</VAR> irrelevant. The Prolog stacks and 
C-thread are reclaimed.

<P>The current implementation does not guarantee proper releasing of all 
mutexes and proper cleanup in <A NAME="idx:setupcallcleanup3:1387"></A><A class="pred" href="metacall.html#setup_call_cleanup/3">setup_call_cleanup/3</A>, 
etc. Please use the exception mechanism (<A NAME="idx:throw1:1388"></A><A class="pred" href="exception.html#throw/1">throw/1</A>) 
to abort execution using non-standard control.</DD>
<DT class="pubdef"><A NAME="thread_initialization/1"><STRONG>thread_initialization</STRONG>(<VAR>:Goal</VAR>)</A></DT>
<DD class="defbody">
Run <VAR>Goal</VAR> when thread is started. This predicate is similar to
<A NAME="idx:initialization1:1389"></A><A class="pred" href="consulting.html#initialization/1">initialization/1</A>, 
but is intended for initialization operations of the runtime stacks, 
such as setting global variables as described in
<A class="sec" href="gvar.html">section 6.3</A>. <VAR>Goal</VAR> is run 
on four occasions: at the call to this predicate, after loading a saved 
state, on starting a new thread and on creating a Prolog engine through 
the C interface. On loading a saved state, <VAR>Goal</VAR> is executed <EM>after</EM> 
running the
<A NAME="idx:initialization1:1390"></A><A class="pred" href="consulting.html#initialization/1">initialization/1</A> 
hooks.</DD>
<DT class="pubdef"><A NAME="thread_at_exit/1"><STRONG>thread_at_exit</STRONG>(<VAR>:Goal</VAR>)</A></DT>
<DD class="defbody">
Run <VAR>Goal</VAR> just before releasing the thread resources. This is 
to be compared to <A NAME="idx:athalt1:1391"></A><A class="pred" href="consulting.html#at_halt/1">at_halt/1</A>, 
but only for the current thread. These hooks are run regardless of why 
the execution of the thread has been completed. As these hooks are run, 
the return-code is already available through
<A NAME="idx:threadproperty2:1392"></A><A class="pred" href="thmonitor.html#thread_property/2">thread_property/2</A> 
using the result of <A NAME="idx:threadself1:1393"></A><A class="pred" href="threadcreate.html#thread_self/1">thread_self/1</A> 
as thread-identifier. See also the <CODE>at_exit(Goal)</CODE> argument 
of
<A NAME="idx:threadcreate3:1394"></A><A class="pred" href="threadcreate.html#thread_create/3">thread_create/3</A>.</DD>
<DT class="pubdef"><A NAME="thread_setconcurrency/2"><STRONG>thread_setconcurrency</STRONG>(<VAR>-Old, 
+New</VAR>)</A></DT>
<DD class="defbody">
<A NAME="idx:Solaris:1395"></A>Determine the concurrency of the process, 
which is defined as the maximum number of concurrently active threads. 
`Active' here means they are using CPU time. This option is provided if 
the thread-implementation provides pthread_setconcurrency(). Solaris is 
a typical example of this family. On other systems this predicate 
unifies <VAR>Old</VAR> to 0 (zero) and succeeds silently.
</DD>
</DL>

<P></BODY></HTML>
swi-prolog-nox 5.10.4-3ubuntu1 / usr / lib / swi-prolog / doc / Manual / threadcreate.html
