/usr/lib/swi-prolog/doc/Manual/threadcom.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.3</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="thmonitor.html">
<LINK REL=next HREF="threadsync.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="thmonitor.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A>
<A class="nav" href="threadsync.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A>
</DIV>

<H2><A NAME="sec:8.3"><SPAN class="sec-nr">8.3</SPAN> <SPAN class="sec-title">Thread 
communication</SPAN></A></H2>

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

<H3><A NAME="sec:8.3.1"><SPAN class="sec-nr">8.3.1</SPAN> <SPAN class="sec-title">Message 
queues</SPAN></A></H3>

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

<P>Prolog threads can exchange data using dynamic predicates, database 
records, and other globally shared data. These provide no suitable means 
to wait for data or a condition as they can only be checked in an 
expensive polling loop. <EM>Message queues</EM> provide a means for 
threads to wait for data or conditions without using the CPU.

<P>Each thread has a message-queue attached to it that is identified by 
the thread. Additional queues are created using
<A NAME="idx:messagequeuecreate1:1404"></A><A class="pred" href="threadcom.html#message_queue_create/1">message_queue_create/1</A>.

<DL class="latex">
<DT class="pubdef"><A NAME="thread_send_message/2"><STRONG>thread_send_message</STRONG>(<VAR>+QueueOrThreadId, 
+Term</VAR>)</A></DT>
<DD class="defbody">
Place <VAR>Term</VAR> in the given queue or default queue of the 
indicated thread (which can even be the message queue of itself, see
<A NAME="idx:threadself1:1405"></A><A class="pred" href="threadcreate.html#thread_self/1">thread_self/1</A>). 
Any term can be placed in a message queue, but note that the term is 
copied to the receiving thread and variable-bindings are thus lost. This 
call returns immediately.

<P>If more than one thread is waiting for messages on the given queue 
and at least one of these is waiting with a partially instantiated
<VAR>Term</VAR>, the waiting threads are <EM>all</EM> sent a wake-up 
signal, starting a rush for the available messages in the queue. This 
behaviour can seriously harm performance with many threads waiting on 
the same queue as all-but-the-winner perform a useless scan of the 
queue. If there is only one waiting thread or all waiting threads wait 
with an unbound variable an arbitrary thread is restarted to scan the 
queue.<SUP class="fn">84<SPAN class="fn-text">See the documentation for 
the POSIX thread functions pthread_cond_signal() v.s. pthread_cond_broadcast() 
for background information.</SPAN></SUP></DD>
<DT class="pubdef"><A NAME="thread_get_message/1"><STRONG>thread_get_message</STRONG>(<VAR>?Term</VAR>)</A></DT>
<DD class="defbody">
Examines the thread message queue and if necessary blocks execution 
until a term that unifies to <VAR>Term</VAR> arrives in the queue. After 
a term from the queue has been unified to <VAR>Term</VAR>, the term is 
deleted from the queue.

<P>Please note that not-unifying messages remain in the queue. After the 
following has been executed, thread 1 has the term <CODE>b(gnu)</CODE> 
in its queue and continues execution using <VAR>A</VAR>&nbsp;=&nbsp;<CODE>gnat</CODE>.

<PRE class="code">
   &lt;thread 1&gt;
   thread_get_message(a(A)),

   &lt;thread 2&gt;
   thread_send_message(Thread_1, b(gnu)),
   thread_send_message(Thread_1, a(gnat)),
</PRE>

<P>See also <A NAME="idx:threadpeekmessage1:1406"></A><A class="pred" href="threadcom.html#thread_peek_message/1">thread_peek_message/1</A>.</DD>
<DT class="pubdef"><A NAME="thread_peek_message/1"><STRONG>thread_peek_message</STRONG>(<VAR>?Term</VAR>)</A></DT>
<DD class="defbody">
Examines the thread message-queue and compares the queued terms with <VAR>Term</VAR> 
until one unifies or the end of the queue has been reached. In the first 
case the call succeeds (possibly instantiating
<VAR>Term</VAR>. If no term from the queue unifies this call fails.</DD>
<DT class="pubdef"><A NAME="message_queue_create/1"><STRONG>message_queue_create</STRONG>(<VAR>?Queue</VAR>)</A></DT>
<DD class="defbody">
If <VAR>Queue</VAR> is an atom, create a named queue. To avoid ambiguity 
of <A NAME="idx:threadsendmessage2:1407"></A><A class="pred" href="threadcom.html#thread_send_message/2">thread_send_message/2</A>, 
the name of a queue may not be in use as a thread-name. If <VAR>Queue</VAR> 
is unbound an anonymous queue is created and <VAR>Queue</VAR> is unified 
to its identifier.</DD>
<DT class="pubdef"><A NAME="message_queue_create/2"><STRONG>message_queue_create</STRONG>(<VAR>-Queue, 
+Options</VAR>)</A></DT>
<DD class="defbody">
Create a message queue from <VAR>Options</VAR>. Defined options are.

<DL class="latex">
<DT><STRONG>alias</STRONG>(<VAR>+Alias</VAR>)</DT>
<DD class="defbody">
Same as <CODE>message_queue_create(Alias)</CODE>, but according to the 
ISO draft on Prolog threads.
</DD>
<DT><STRONG>max_size</STRONG>(<VAR>+Size</VAR>)</DT>
<DD class="defbody">
Maximum number of terms in the queue. If this number is reached,
<A NAME="idx:threadsendmessage2:1408"></A><A class="pred" href="threadcom.html#thread_send_message/2">thread_send_message/2</A> 
will suspend until the queue is drained. The option can be used if the 
source, sending messages to the queue, is faster than the drain, 
consuming the messages.
</DD>
</DL>

</DD>
<DT class="pubdef"><A NAME="message_queue_destroy/1"><STRONG>message_queue_destroy</STRONG>(<VAR>+Queue</VAR>)</A></DT>
<DD class="defbody">
Destroy a message queue created with <A NAME="idx:messagequeuecreate1:1409"></A><A class="pred" href="threadcom.html#message_queue_create/1">message_queue_create/1</A>. 
A permission error is raised if <VAR>Queue</VAR> refers to (the default 
queue of) a thread. Other threads are waiting for <VAR>Queue</VAR> using
<A NAME="idx:threadgetmessage2:1410"></A><A class="pred" href="threadcom.html#thread_get_message/2">thread_get_message/2</A> 
receive an existence error.</DD>
<DT class="pubdef"><A NAME="thread_get_message/2"><STRONG>thread_get_message</STRONG>(<VAR>+Queue, 
?Term</VAR>)</A></DT>
<DD class="defbody">
As <A NAME="idx:threadgetmessage1:1411"></A><A class="pred" href="threadcom.html#thread_get_message/1">thread_get_message/1</A>, 
operating on a given queue. It is allowed (but not advised) to get 
messages from the queue of other threads.</DD>
<DT class="pubdef"><A NAME="thread_peek_message/2"><STRONG>thread_peek_message</STRONG>(<VAR>+Queue, 
?Term</VAR>)</A></DT>
<DD class="defbody">
As <A NAME="idx:threadpeekmessage1:1412"></A><A class="pred" href="threadcom.html#thread_peek_message/1">thread_peek_message/1</A>, 
operating on a given queue. It is allowed to peek into another thread's 
message queue, an operation that can be used to check whether a thread 
has swallowed a message sent to it.</DD>
<DT class="pubdef"><A NAME="message_queue_property/2"><STRONG>message_queue_property</STRONG>(<VAR>?Queue, 
?Property</VAR>)</A></DT>
<DD class="defbody">
True if <VAR>Property</VAR> is a property of <VAR>Queue</VAR>. Defined 
properties are:

<DL class="latex">
<DT><STRONG>alias</STRONG>(<VAR>Alias</VAR>)</DT>
<DD class="defbody">
Queue has the given alias name.
</DD>
<DT><STRONG>size</STRONG>(<VAR>Size</VAR>)</DT>
<DD class="defbody">
Queue currently contains <VAR>Size</VAR> terms. Note that due to 
concurrent access the returned value may be outdated before it is 
returned. It can be used for debugging purposes as well as work 
distribution purposes.
</DD>
</DL>

</DD>
</DL>

<P>Explicit message queues are designed with the <EM>worker-pool</EM> 
model in mind, where multiple threads wait on a single queue and pick up 
the first goal to execute. Below is a simple implementation where the 
workers execute arbitrary Prolog goals. Note that this example provides 
no means to tell when all work is done. This must be realised using 
additional synchronisation.

<PRE class="code">
%       create_workers(+Id, +N)
%
%       Create a pool with given Id and number of workers.

create_workers(Id, N) :-
        message_queue_create(Id),
        forall(between(1, N, _),
               thread_create(do_work(Id), _, [])).

do_work(Id) :-
        repeat,
          thread_get_message(Id, Goal),
          (   catch(Goal, E, print_message(error, E))
          -&gt;  true
          ;   print_message(error, goal_failed(Goal, worker(Id)))
          ),
        fail.

%       work(+Id, +Goal)
%
%       Post work to be done by the pool

work(Id, Goal) :-
        thread_send_message(Id, Goal).
</PRE>

<H3><A NAME="sec:8.3.2"><SPAN class="sec-nr">8.3.2</SPAN> <SPAN class="sec-title">Signalling 
threads</SPAN></A></H3>

<P>These predicates provide a mechanism to make another thread execute 
some goal as an <EM>interrupt</EM>. Signalling threads is safe as these 
interrupts are only checked at safe points in the virtual machine. 
Nevertheless, signalling in multi-threaded environments should be 
handled with care as the receiving thread may hold a <EM>mutex</EM> (see 
with_mutex). Signalling probably only makes sense to start debugging 
threads and to cancel no-longer-needed threads with <A NAME="idx:throw1:1413"></A><A class="pred" href="exception.html#throw/1">throw/1</A>, 
where the receiving thread should be designed carefully to handle 
exceptions at any point.

<DL class="latex">
<DT class="pubdef"><A NAME="thread_signal/2"><STRONG>thread_signal</STRONG>(<VAR>+ThreadId, 
:Goal</VAR>)</A></DT>
<DD class="defbody">
Make thread <VAR>ThreadId</VAR> execute <VAR>Goal</VAR> at the first 
opportunity. In the current implementation, this implies at the first 
pass through the <EM>Call-port</EM>. The predicate <A NAME="idx:threadsignal2:1414"></A><A class="pred" href="threadcom.html#thread_signal/2">thread_signal/2</A> 
itself places <VAR>Goal</VAR> into the signalled-thread's signal queue 
and returns immediately.

<P>Signals (interrupts) do not cooperate well with the world of 
multi-threading, mainly because the status of mutexes cannot be 
guaranteed easily. At the call-port, the Prolog virtual machine holds no 
locks and therefore the asynchronous execution is safe.

<P><VAR>Goal</VAR> can be any valid Prolog goal, including <A NAME="idx:throw1:1415"></A><A class="pred" href="exception.html#throw/1">throw/1</A> 
to make the receiving thread generate an exception and <A NAME="idx:trace0:1416"></A><A class="pred" href="debugger.html#trace/0">trace/0</A> 
to start tracing the receiving thread.

<P>In the Windows version, the receiving thread immediately executes the 
signal if it reaches a Windows GetMessage() call, which generally 
happens if the thread is waiting for (user-)input.
</DD>
</DL>

<H3><A NAME="sec:8.3.3"><SPAN class="sec-nr">8.3.3</SPAN> <SPAN class="sec-title">Threads 
and dynamic predicates</SPAN></A></H3>

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

<P>Besides queues (<A class="sec" href="threadcom.html">section 8.3.1</A>) 
threads can share and exchange data using dynamic predicates. The 
multi-threaded version knows about two types of dynamic predicates. By 
default, a predicate declared
<EM>dynamic</EM> (see <A NAME="idx:dynamic1:1417"></A><A class="pred" href="dynamic.html#dynamic/1">dynamic/1</A>) 
is shared by all threads. Each thread may assert, retract and run the 
dynamic predicate. Synchronisation inside Prolog guarantees the 
consistency of the predicate. Updates are
<EM>logical</EM>: visible clauses are not affected by assert/retract 
after a query started on the predicate. In many cases primitives from
<A class="sec" href="threadsync.html">section 8.4</A> should be used to 
ensure that application invariants on the predicate are maintained.

<P>Besides shared predicates, dynamic predicates can be declared with 
the
<A NAME="idx:threadlocal1:1418"></A><A class="pred" href="threadcom.html#thread_local/1">thread_local/1</A> 
directive. Such predicates share their attributes, but the clause-list 
is different in each thread.

<DL class="latex">
<DT class="pubdef"><A NAME="thread_local/1"><STRONG>thread_local</STRONG> <VAR>+Functor/+Arity, \ldots</VAR></A></DT>
<DD class="defbody">
This directive is related to the <A NAME="idx:dynamic1:1419"></A><A class="pred" href="dynamic.html#dynamic/1">dynamic/1</A> 
directive. It tells the system that the predicate may be modified using <A NAME="idx:assert1:1420"></A><A class="pred" href="db.html#assert/1">assert/1</A>, <A NAME="idx:retract1:1421"></A><A class="pred" href="db.html#retract/1">retract/1</A>, 
etc. during execution of the program. Unlike normal shared dynamic data 
however each thread has its own clause-list for the predicate. As a 
thread starts, this clause list is empty. If there are still clauses 
when the thread terminates, these are automatically reclaimed by the 
system (see also <A NAME="idx:volatile1:1422"></A><A class="pred" href="runtime.html#volatile/1">volatile/1</A>). 
The thread_local property implies the properties dynamic and volatile.

<P>Thread-local dynamic predicates are intended for maintaining 
thread-specific state or intermediate results of a computation.

<P>It is not recommended to put clauses for a thread-local predicate 
into a file as in the example below because the clause is only visible 
from the thread that loaded the source-file. All other threads start 
with an empty clause-list.

<PRE class="code">
:- thread_local
        foo/1.

foo(gnat).
</PRE>

<P><B>DISCLAIMER</B> Whether or not this declaration is appropriate in 
the sense of the proper mechanism to reach the goal is still debated. If 
you have strong feeling in favour or against, please share them in the 
SWI-Prolog mailing list.
</DD>
</DL>

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