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

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

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

<P>All internal Prolog operations are thread-safe. This implies two 
Prolog threads can operate on the same dynamic predicate without 
corrupting the consistency of the predicate. This section deals with 
user-level
<EM>mutexes</EM> (called <EM>monitors</EM> in ADA or
<EM>critical-sections</EM> by Microsoft). A mutex is a
<B>MUT</B>ual <B>EX</B>clusive device, which implies at most one thread 
can <EM>hold</EM> a mutex.

<P>Mutexes are used to realise related updates to the Prolog database. 
With `related', we refer to the situation where a `transaction' implies 
two or more changes to the Prolog database. For example, we have a 
predicate address/2 , representing the address of a person and we want 
to change the address by retracting the old and asserting the new 
address. Between these two operations the database is invalid: this 
person has either no address or two addresses, depending on the 
assert/retract order.

<P>Here is how to realise a correct update:

<PRE class="code">
:- initialization
        mutex_create(addressbook).

change_address(Id, Address) :-
        mutex_lock(addressbook),
        retractall(address(Id, _)),
        asserta(address(Id, Address)),
        mutex_unlock(addressbook).
</PRE>

<DL class="latex">
<DT class="pubdef"><A NAME="mutex_create/1"><STRONG>mutex_create</STRONG>(<VAR>?MutexId</VAR>)</A></DT>
<DD class="defbody">
Create a mutex. If <VAR>MutexId</VAR> is an atom, a <EM>named</EM> mutex 
is created. If it is a variable, an anonymous mutex reference is 
returned. There is no limit to the number of mutexes that can be 
created.</DD>
<DT class="pubdef"><A NAME="mutex_create/2"><STRONG>mutex_create</STRONG>(<VAR>-MutexId, 
+Options</VAR>)</A></DT>
<DD class="defbody">
Create a mutex using options. Defined options are:

<DL class="latex">
<DT><STRONG>alias</STRONG>(<VAR>Alias</VAR>)</DT>
<DD class="defbody">
Set the alias name. Using <CODE>mutex_create(X, [alias(name)])</CODE> is 
preferred over the equivalent <CODE>mutex_create(name)</CODE>.
</DD>
</DL>

</DD>
<DT class="pubdef"><A NAME="mutex_destroy/1"><STRONG>mutex_destroy</STRONG>(<VAR>+MutexId</VAR>)</A></DT>
<DD class="defbody">
Destroy a mutex. After this call, <VAR>MutexId</VAR> becomes invalid and 
further references yield an <CODE>existence_error</CODE> exception.</DD>
<DT class="pubdef"><A NAME="with_mutex/2"><STRONG>with_mutex</STRONG>(<VAR>+MutexId, 
:Goal</VAR>)</A></DT>
<DD class="defbody">
Execute <VAR>Goal</VAR> while holding <VAR>MutexId</VAR>. If <VAR>Goal</VAR> 
leaves choice-points, these are destroyed (as in <A NAME="idx:once1:1423"></A><A class="pred" href="metacall.html#once/1">once/1</A>). 
The mutex is unlocked regardless of whether <VAR>Goal</VAR> succeeds, 
fails or raises an exception. An exception thrown by <VAR>Goal</VAR> is 
re-thrown after the mutex has been successfully unlocked. See also <A NAME="idx:mutexcreate1:1424"></A><A class="pred" href="threadsync.html#mutex_create/1">mutex_create/1</A> 
and <A NAME="idx:setupcallcleanup3:1425"></A><A class="pred" href="metacall.html#setup_call_cleanup/3">setup_call_cleanup/3</A>.

<P>Although described in the thread-section, this predicate is also 
available in the single-threaded version, where it behaves simply as
<A NAME="idx:once1:1426"></A><A class="pred" href="metacall.html#once/1">once/1</A>.</DD>
<DT class="pubdef"><A NAME="mutex_lock/1"><STRONG>mutex_lock</STRONG>(<VAR>+MutexId</VAR>)</A></DT>
<DD class="defbody">
Lock the mutex. Prolog mutexes are <EM>recursive</EM> mutexes: they can 
be locked multiple times by the same thread. Only after unlocking it as 
many times as it is locked, the mutex becomes available for locking by 
other threads. If another thread has locked the mutex the calling thread 
is suspended until to mutex is unlocked.

<P>If <VAR>MutexId</VAR> is an atom, and there is no current mutex with 
that name, the mutex is created automatically using <A NAME="idx:mutexcreate1:1427"></A><A class="pred" href="threadsync.html#mutex_create/1">mutex_create/1</A>. 
This implies named mutexes need not be declared explicitly.

<P>Please note that locking and unlocking mutexes should be paired 
carefully. Especially make sure to unlock mutexes even if the protected 
code fails or raises an exception. For most common cases use
<A NAME="idx:withmutex2:1428"></A><A class="pred" href="threadsync.html#with_mutex/2">with_mutex/2</A>, 
which provides a safer way for handling Prolog-level mutexes. The 
predicate <A NAME="idx:setupcallcleanup3:1429"></A><A class="pred" href="metacall.html#setup_call_cleanup/3">setup_call_cleanup/3</A> 
is another way to guarantee that the mutex is unlocked while retaining 
non-determinism.</DD>
<DT class="pubdef"><A NAME="mutex_trylock/1"><STRONG>mutex_trylock</STRONG>(<VAR>+MutexId</VAR>)</A></DT>
<DD class="defbody">
As <A NAME="idx:mutexlock1:1430"></A><A class="pred" href="threadsync.html#mutex_lock/1">mutex_lock/1</A>, 
but if the mutex is held by another thread, this predicates fails 
immediately.</DD>
<DT class="pubdef"><A NAME="mutex_unlock/1"><STRONG>mutex_unlock</STRONG>(<VAR>+MutexId</VAR>)</A></DT>
<DD class="defbody">
Unlock the mutex. This can only be called if the mutex is held by the 
calling thread. If this is not the case, a <CODE>permission_error</CODE> 
exception is raised.</DD>
<DT class="pubdef"><A NAME="mutex_unlock_all/0"><STRONG>mutex_unlock_all</STRONG></A></DT>
<DD class="defbody">
Unlock all mutexes held by the current thread. This call is especially 
useful to handle thread-termination using <A NAME="idx:abort0:1431"></A><A class="pred" href="toplevel.html#abort/0">abort/0</A> 
or exceptions. See also <A NAME="idx:threadsignal2:1432"></A><A class="pred" href="threadcom.html#thread_signal/2">thread_signal/2</A>.</DD>
<DT class="pubdef"><A NAME="mutex_property/2"><STRONG>mutex_property</STRONG>(<VAR>?MutexId, 
?Property</VAR>)</A></DT>
<DD class="defbody">
True if Property is a property of MutexId. Defined properties are:

<DL class="latex">
<DT><STRONG>alias</STRONG>(<VAR>Alias</VAR>)</DT>
<DD class="defbody">
Mutex has defined alias name. See <A NAME="idx:mutexcreate2:1433"></A><A class="pred" href="threadsync.html#mutex_create/2">mutex_create/2</A> 
using the `alias' option.</DD>
<DT><STRONG>status</STRONG>(<VAR>Status</VAR>)</DT>
<DD class="defbody">
Current status of the mutex. One of <CODE>unlocked</CODE> if the mutex 
is currently not locked or <CODE>locked(Owner, Count)</CODE> if mutex is 
locked
<VAR>Count</VAR> times by threads <VAR>Owner</VAR>. Note that, unless <VAR>Owner</VAR> 
is the calling thread, the locked status can change at any time. There 
is no useful application of this property, except for diagnostic 
purposes.<SUP class="fn">bug<SPAN class="fn-text">As <VAR>Owner</VAR> 
and <VAR>Count</VAR> are fetched separately from the mutex, the values 
may be inconsistent.</SPAN></SUP>
</DD>
</DL>

</DD>
</DL>

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