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

<H2><A NAME="sec:6.3"><SPAN class="sec-nr">6.3</SPAN> <SPAN class="sec-title">Global 
variables</SPAN></A></H2>

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

<P>Global variables are associations between names (atoms) and terms. 
They differ in various ways from storing information using <A NAME="idx:assert1:1328"></A><A class="pred" href="db.html#assert/1">assert/1</A> 
or <A NAME="idx:recorda3:1329"></A><A class="pred" href="db.html#recorda/3">recorda/3</A>.

<P>
<UL class="latex">
<LI>The value lives on the Prolog (global) stack. This implies that 
lookup time is independent from the size of the term. This is 
particularly interesting for large data structures such as parsed XML 
documents or the CHR global constraint store.

<P>
<LI>They support both global assignment using <A NAME="idx:nbsetval2:1330"></A><A class="pred" href="gvar.html#nb_setval/2">nb_setval/2</A> 
and backtrackable assignment using <A NAME="idx:bsetval2:1331"></A><A class="pred" href="gvar.html#b_setval/2">b_setval/2</A>.

<P>
<LI>Only one value (which can be an arbitrary complex Prolog term) can 
be associated to a variable at a time.

<P>
<LI>Their value cannot be shared among threads. Each thread has its own 
namespace and values for global variables.

<P>
<LI>Currently global variables are scoped globally. We may consider 
module scoping in future versions.
</UL>

<P>Both <A NAME="idx:bsetval2:1332"></A><A class="pred" href="gvar.html#b_setval/2">b_setval/2</A> 
and <A NAME="idx:nbsetval2:1333"></A><A class="pred" href="gvar.html#nb_setval/2">nb_setval/2</A> 
implicitly create a variable if the referenced name does not already 
refer to a variable.

<P>Global variables may be initialised from directives to make them 
available during the program lifetime, but some considerations are 
necessary for saved-states and threads. Saved-states to not store global 
variables, which implies they have to be declared with <A NAME="idx:initialization1:1334"></A><A class="pred" href="consulting.html#initialization/1">initialization/1</A> 
to recreate them after loading the saved state. Each thread has its own 
set of global variables, starting with an empty set. Using
<A NAME="idx:threadinitialization1:1335"></A><A class="pred" href="threadcreate.html#thread_initialization/1">thread_initialization/1</A> 
to define a global variable it will be defined, restored after reloading 
a saved state and created in all threads that are created <EM>after</EM> 
the registration. Finally, global variables can be initialised using the 
exception hook called
<A NAME="idx:exception3:1336"></A><A class="pred" href="exception3.html#exception/3">exception/3</A>. 
The latter technique is by CHR (see <A class="sec" href="chr.html">chapter 
7</A>.

<DL class="latex">
<DT class="pubdef"><A NAME="b_setval/2"><STRONG>b_setval</STRONG>(<VAR>+Name, 
+Value</VAR>)</A></DT>
<DD class="defbody">
Associate the term <VAR>Value</VAR> with the atom <VAR>Name</VAR> or 
replaces the currently associated value with <VAR>Value</VAR>. If <VAR>Name</VAR> 
does not refer to an existing global variable a variable with initial 
value
<CODE>[]</CODE> is created (the empty list). On backtracking the 
assignment is reversed.</DD>
<DT class="pubdef"><A NAME="b_getval/2"><STRONG>b_getval</STRONG>(<VAR>+Name, 
-Value</VAR>)</A></DT>
<DD class="defbody">
Get the value associated with the global variable <VAR>Name</VAR> and 
unify it with <VAR>Value</VAR>. Note that this unification may further 
instantiate the value of the global variable. If this is undesirable the 
normal precautions (double negation or <A NAME="idx:copyterm2:1337"></A><A class="pred" href="manipterm.html#copy_term/2">copy_term/2</A>) 
must be taken. The
<A NAME="idx:bgetval2:1338"></A><A class="pred" href="gvar.html#b_getval/2">b_getval/2</A> 
predicate generates errors if <VAR>Name</VAR> is not an atom or the 
requested variable does not exist.
</DD>
</DL>

<DL class="latex">
<DT class="pubdef"><A NAME="nb_setval/2"><STRONG>nb_setval</STRONG>(<VAR>+Name, 
+Value</VAR>)</A></DT>
<DD class="defbody">
Associates a copy of <VAR>Value</VAR> created with <A NAME="idx:duplicateterm2:1339"></A><A class="pred" href="manipterm.html#duplicate_term/2">duplicate_term/2</A> 
with the atom <VAR>Name</VAR>. Note that this can be used to set an 
initial value other than <CODE>[]</CODE> prior to backtrackable 
assignment.</DD>
<DT class="pubdef"><A NAME="nb_getval/2"><STRONG>nb_getval</STRONG>(<VAR>+Name, 
-Value</VAR>)</A></DT>
<DD class="defbody">
The <A NAME="idx:nbgetval2:1340"></A><A class="pred" href="gvar.html#nb_getval/2">nb_getval/2</A> 
predicate is a synonym for <A NAME="idx:bgetval2:1341"></A><A class="pred" href="gvar.html#b_getval/2">b_getval/2</A>, 
introduced for compatibility and symmetry. As most scenarios will use a 
particular global variable either using non-backtrackable or 
backtrackable assignment, using <A NAME="idx:nbgetval2:1342"></A><A class="pred" href="gvar.html#nb_getval/2">nb_getval/2</A> 
can be used to document that the variable is used non-backtrackable.</DD>
<DT class="pubdef"><A NAME="nb_linkval/2"><STRONG>nb_linkval</STRONG>(<VAR>+Name, 
+Value</VAR>)</A></DT>
<DD class="defbody">
Associates the term <VAR>Value</VAR> with the atom <VAR>Name</VAR> 
without copying it. This is a fast special-purpose variation of <A NAME="idx:nbsetval2:1343"></A><A class="pred" href="gvar.html#nb_setval/2">nb_setval/2</A> 
intended for expert users only because the semantics on backtracking to 
a point before creating the link are poorly defined for compound terms. 
The principal term is always left untouched, but backtracking behaviour 
on arguments is undone if the original assignment was <EM>trailed</EM> 
and left alone otherwise, which implies that the history that created 
the term affects the behaviour on backtracking. Please consider the 
following example:

<PRE class="code">
demo_nb_linkval :-
        T = nice(N),
        (   N = world,
            nb_linkval(myvar, T),
            fail
        ;   nb_getval(myvar, V),
            writeln(V)
        ).
</PRE>

</DD>
<DT class="pubdef"><A NAME="nb_current/2"><STRONG>nb_current</STRONG>(<VAR>?Name, 
?Value</VAR>)</A></DT>
<DD class="defbody">
Enumerate all defined variables with their value. The order of 
enumeration is undefined.</DD>
<DT class="pubdef"><A NAME="nb_delete/1"><STRONG>nb_delete</STRONG>(<VAR>+Name</VAR>)</A></DT>
<DD class="defbody">
Delete the named global variable.
</DD>
</DL>

<H3><A NAME="sec:6.3.1"><SPAN class="sec-nr">6.3.1</SPAN> <SPAN class="sec-title">Compatibility 
of SWI-Prolog Global Variables</SPAN></A></H3>

<P>Global variables have been introduced by various Prolog 
implementations recently. The implementation of them in SWI-Prolog is 
based on hProlog by Bart Demoen. In discussion with Bart it was decided 
that the semantics if hProlog <A NAME="idx:nbsetval2:1344"></A><A class="pred" href="gvar.html#nb_setval/2">nb_setval/2</A>, 
which is equivalent to <A NAME="idx:nblinkval2:1345"></A><A class="pred" href="gvar.html#nb_linkval/2">nb_linkval/2</A> 
is not acceptable for normal Prolog users as the behaviour is influenced 
by how built-in predicates constructing terms (<A NAME="idx:read1:1346"></A><A class="pred" href="termrw.html#read/1">read/1</A>, 
=../2, etc.) are implemented.

<P>GNU-Prolog provides a rich set of global variables, including arrays. 
Arrays can be implemented easily in SWI-Prolog using <A NAME="idx:functor3:1347"></A><A class="pred" href="manipterm.html#functor/3">functor/3</A> 
and
<A NAME="idx:setarg3:1348"></A><A class="pred" href="manipterm.html#setarg/3">setarg/3</A> 
due to the unrestricted arity of compound terms.

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