mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-26 07:11:34 -08:00
Code Issues Projects Releases Wiki Activity
emacs/mps/manual/html/topic/location.html
Gareth Rees eaad4493d4 Bring html up to date. 
Copied from Perforce
 Change: 181731
 ServerID: perforce.ravenbrook.com
2013-05-11 20:07:28 +01:00

412 lines
No EOL
35 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>14. Location dependency &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.111.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="15. Segregated allocation caches" href="cache.html" />
<link rel="prev" title="13. Finalization" href="finalization.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="cache.html" title="15. Segregated allocation caches"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="finalization.html" title="13. Finalization"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="location-dependency">
<span id="topic-location"></span><span id="index-0"></span><h1>14. Location dependency<a class="headerlink" href="#location-dependency" title="Permalink to this headline"></a></h1>
<p>Location dependencies provide a means by which the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client
program</em></a> can depend on the <em class="dfn">location</em> of blocks (that is, on the
bits in pointers to the blocks) in the presence of a <a class="reference internal" href="../glossary/m.html#term-moving-memory-manager"><em class="xref std std-term">moving
memory manager</em></a> (where the location of blocks may change and the
client program needs to recognize and correctly deal with such cases).</p>
<p>The interface is intended to support (amongst other things)
address-based hash tables and that will be used as a running example.
See the section <a class="reference internal" href="../guide/advanced.html#guide-advanced-location"><em>Location dependency</em></a> in the Guide for a more
detailed look at this example.</p>
<div class="section" id="terminology">
<h2>14.1. Terminology<a class="headerlink" href="#terminology" title="Permalink to this headline"></a></h2>
<p>A <em class="dfn">location dependency</em> is represented by an structure of type
<a class="reference internal" href="#mps_ld_s" title="mps_ld_s"><tt class="xref c c-type docutils literal"><span class="pre">mps_ld_s</span></tt></a>. It encapsulates a set of dependencies on the
locations of blocks. It can be used to determine whether any of the
blocks have been moved by the memory manager.</p>
<p>To <em class="dfn">depend</em> on the location of a block is to perform a computation
whose result depends on the particular representation (that is, the
&#8220;bit-pattern&#8221;) of a reference to the block. This includes any sort of
hash operation on a pointer to the block (such as treating the
pointer as an integer and taking it modulo 257). It is possible to
depend on the location of more than one block.</p>
<p>A dependency has been made <em class="dfn">stale</em> if the block whose location was
depended on might have moved since the dependency was made. If this is
the case, then computations that depend on the location of a block
may give different results. A location dependency has been made stale
if any of the blocks whose location has been depended on might have
moved since the respective dependency was made.</p>
</div>
<div class="section" id="creating-dependencies">
<span id="index-1"></span><h2>14.2. Creating dependencies<a class="headerlink" href="#creating-dependencies" title="Permalink to this headline"></a></h2>
<p>The <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> must provide space for the
<a class="reference internal" href="#mps_ld_s" title="mps_ld_s"><tt class="xref c c-type docutils literal"><span class="pre">mps_ld_s</span></tt></a> structure. Typically, this will be inlined in some
larger structure. This structure can be in memory managed by the MPS
or elsewhere; that doesn&#8217;t matter.</p>
<p>For example, the toy Scheme interpreter inlines the location
dependency in its hash table structure:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">table_s</span> <span class="p">{</span>
<span class="n">type_t</span> <span class="n">type</span><span class="p">;</span> <span class="cm">/* TYPE_TABLE */</span>
<span class="n">hash_t</span> <span class="n">hash</span><span class="p">;</span> <span class="cm">/* hash function */</span>
<span class="n">cmp_t</span> <span class="n">cmp</span><span class="p">;</span> <span class="cm">/* comparison function */</span>
<span class="hll"> <span class="n">mps_ld_s</span> <span class="n">ld</span><span class="p">;</span> <span class="cm">/* location dependency */</span>
</span> <span class="n">obj_t</span> <span class="n">buckets</span><span class="p">;</span> <span class="cm">/* hash buckets */</span>
<span class="p">}</span> <span class="n">table_s</span><span class="p">;</span>
</pre></div>
</div>
<p>Before the first use, the location dependency must be reset by calling
the function <a class="reference internal" href="#mps_ld_reset" title="mps_ld_reset"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_reset()</span></tt></a>.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">This means that it is not possible to statically create a location
dependency that has been reset.</p>
</div>
<p>You can call <a class="reference internal" href="#mps_ld_reset" title="mps_ld_reset"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_reset()</span></tt></a> at any later point to clear all
dependencies from the structure. For example, this is normally done
whenever <a class="reference internal" href="#mps_ld_isstale" title="mps_ld_isstale"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_isstale()</span></tt></a> returns true.</p>
</div>
<div class="section" id="adding-dependencies">
<span id="index-2"></span><h2>14.3. Adding dependencies<a class="headerlink" href="#adding-dependencies" title="Permalink to this headline"></a></h2>
<p><em>Before</em> the location of a block is depended on (for example,
hashed) a reference to the block may be added to a location
dependency by calling <a class="reference internal" href="#mps_ld_add" title="mps_ld_add"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_add()</span></tt></a>. Dependencies on many
blocks can be added to the same location dependency.</p>
<p>It is also possible to merge two location dependencies by calling
<a class="reference internal" href="#mps_ld_merge" title="mps_ld_merge"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_merge()</span></tt></a>, which has the same effect as adding all of the
references from one dependency to another.</p>
<p>For example, in an address-based hash table implementation, each key
that is added to the table must be added to the dependency before its
address is hashed. In the toy Scheme interpreter this is most easily
done in the function that hashes an address:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">unsigned</span> <span class="kt">long</span> <span class="nf">eq_hash</span><span class="p">(</span><span class="n">obj_t</span> <span class="n">obj</span><span class="p">,</span> <span class="n">mps_ld_t</span> <span class="n">ld</span><span class="p">)</span>
<span class="p">{</span>
<span class="k">union</span> <span class="p">{</span><span class="kt">char</span> <span class="n">s</span><span class="p">[</span><span class="k">sizeof</span><span class="p">(</span><span class="n">obj_t</span><span class="p">)];</span> <span class="n">obj_t</span> <span class="n">addr</span><span class="p">;}</span> <span class="n">u</span><span class="p">;</span>
<span class="hll"> <span class="k">if</span> <span class="p">(</span><span class="n">ld</span><span class="p">)</span> <span class="n">mps_ld_add</span><span class="p">(</span><span class="n">ld</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">obj</span><span class="p">);</span>
</span> <span class="n">u</span><span class="p">.</span><span class="n">addr</span> <span class="o">=</span> <span class="n">obj</span><span class="p">;</span>
<span class="k">return</span> <span class="n">hash</span><span class="p">(</span><span class="n">u</span><span class="p">.</span><span class="n">s</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">obj_t</span><span class="p">));</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="testing-dependencies-for-staleness">
<span id="index-3"></span><h2>14.4. Testing dependencies for staleness<a class="headerlink" href="#testing-dependencies-for-staleness" title="Permalink to this headline"></a></h2>
<p>When the locations of blocks are used (during a hash table lookup for
example), the computation should be carried out and the result used in
the usual way (for example, the pointer is hashed and the has used to
index into the table). At this point one of three situations can
occur:</p>
<ol class="arabic simple">
<li>success (for example, the key was found in the table at the place
indicated by the hash of its address);</li>
<li>failure: the location of these blocks has not been depended on
before (for example, the key has never been added to the hash
table);</li>
<li>failure: the location of these blocks has been depended on before,
but the one or more of the blocks has moved and the dependency has
been made stale (in this case the table would need to be rehashed
and the lookup repeated).</li>
</ol>
<p>Success requires no further test: the operation can proceed. In case
of failure, you should call <a class="reference internal" href="#mps_ld_isstale" title="mps_ld_isstale"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_isstale()</span></tt></a>. If it returns
false, then no blocks have moved, so you must be in case (2).</p>
<p>But if <a class="reference internal" href="#mps_ld_isstale" title="mps_ld_isstale"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_isstale()</span></tt></a> returns true, you could still be in
either case (2) or case (3). All <a class="reference internal" href="#mps_ld_isstale" title="mps_ld_isstale"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_isstale()</span></tt></a> tells you is
that some blocks that have been depended on might have moved. At this
point you need to:</p>
<ol class="arabic simple">
<li>reset the location dependency;</li>
<li>repeat the computation in some way that doesn&#8217;t depend on the
old locations of the blocks; and</li>
<li>re-add a dependency on each block.</li>
</ol>
<p>For example, in the case of a hash table you should rehash based on
the new locations of the blocks.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="n">obj_t</span> <span class="nf">table_ref</span><span class="p">(</span><span class="n">obj_t</span> <span class="n">tbl</span><span class="p">,</span> <span class="n">obj_t</span> <span class="n">key</span><span class="p">)</span>
<span class="p">{</span>
<span class="k">struct</span> <span class="n">bucket_s</span> <span class="o">*</span><span class="n">b</span> <span class="o">=</span> <span class="n">buckets_find</span><span class="p">(</span><span class="n">tbl</span><span class="p">,</span> <span class="n">tbl</span><span class="o">-&gt;</span><span class="n">table</span><span class="p">.</span><span class="n">buckets</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">b</span> <span class="o">&amp;&amp;</span> <span class="n">b</span><span class="o">-&gt;</span><span class="n">key</span> <span class="o">!=</span> <span class="nb">NULL</span> <span class="o">&amp;&amp;</span> <span class="n">b</span><span class="o">-&gt;</span><span class="n">key</span> <span class="o">!=</span> <span class="n">obj_deleted</span><span class="p">)</span>
<span class="k">return</span> <span class="n">b</span><span class="o">-&gt;</span><span class="n">value</span><span class="p">;</span>
<span class="hll"> <span class="k">if</span> <span class="p">(</span><span class="n">mps_ld_isstale</span><span class="p">(</span><span class="o">&amp;</span><span class="n">tbl</span><span class="o">-&gt;</span><span class="n">table</span><span class="p">.</span><span class="n">ld</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">key</span><span class="p">))</span> <span class="p">{</span>
</span> <span class="n">b</span> <span class="o">=</span> <span class="n">table_rehash</span><span class="p">(</span><span class="n">tbl</span><span class="p">,</span> <span class="n">tbl</span><span class="o">-&gt;</span><span class="n">table</span><span class="p">.</span><span class="n">buckets</span><span class="o">-&gt;</span><span class="n">buckets</span><span class="p">.</span><span class="n">length</span><span class="p">,</span> <span class="n">key</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="k">return</span> <span class="n">b</span><span class="o">-&gt;</span><span class="n">value</span><span class="p">;</span>
<span class="p">}</span>
<span class="k">return</span> <span class="nb">NULL</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>After <a class="reference internal" href="#mps_ld_isstale" title="mps_ld_isstale"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_isstale()</span></tt></a> has returned true, and you&#8217;ve rehashed
the table, it might be tempting to repeat the usual address-based
lookup. But the MPS does not guarantee that <a class="reference internal" href="#mps_ld_isstale" title="mps_ld_isstale"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_isstale()</span></tt></a>
will not return true again: if the re-hashing took a long time or
touched lots of memory, there might have been another garbage
collection. (The only time that <a class="reference internal" href="#mps_ld_isstale" title="mps_ld_isstale"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_isstale()</span></tt></a> guarantees to
return false is immediately after <a class="reference internal" href="#mps_ld_reset" title="mps_ld_reset"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_reset()</span></tt></a>.)</p>
<p>You might put in a loop here, but for reliability it is better to fall
back to a non-address-based version of the computation: here, since
<tt class="docutils literal"><span class="pre">table_rehash</span></tt> has to loop over all the entries in the table anyway,
it might as well find the bucket containing <tt class="docutils literal"><span class="pre">key</span></tt> at the same time
and return it.</p>
</div>
<div class="section" id="thread-safety">
<span id="index-4"></span><h2>14.5. Thread safety<a class="headerlink" href="#thread-safety" title="Permalink to this headline"></a></h2>
<p>The functions are all thread-safe with respect to operations on
different location dependencies. That means that it is not necessary
for threads to interlock if they are performing operations on
different location dependencies. The descriptions of the individual
functions detail their thread-safety attributes if multiple threads
need to access the same location dependency.</p>
</div>
<div class="section" id="location-dependency-interface">
<span id="index-5"></span><h2>14.6. Location dependency interface<a class="headerlink" href="#location-dependency-interface" title="Permalink to this headline"></a></h2>
<dl class="type">
<dt id="mps_ld_t">
<tt class="descname">mps_ld_t</tt><a class="headerlink" href="#mps_ld_t" title="Permalink to this definition"></a></dt>
<dd><p>The type of <a class="reference internal" href="../glossary/l.html#term-location-dependency"><em class="xref std std-term">location dependencies</em></a>. It is a
<a class="reference internal" href="../glossary/t.html#term-transparent-type"><em class="xref std std-term">transparent alias</em></a> for a pointer to
<a class="reference internal" href="#mps_ld_s" title="mps_ld_s"><tt class="xref c c-type docutils literal"><span class="pre">mps_ld_s</span></tt></a>.</p>
<p>A location dependency records the fact that the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client
program</em></a> depends on the bit patterns of some <a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">references</em></a>
(and not merely on the identity of the <a class="reference internal" href="../glossary/b.html#term-block"><em class="xref std std-term">block</em></a> to which the
reference refers), and provides a function
(<a class="reference internal" href="#mps_ld_isstale" title="mps_ld_isstale"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_isstale()</span></tt></a>) to find out whether any of these
references have been changed because a block has been <a class="reference internal" href="../glossary/m.html#term-moving-garbage-collector"><em class="xref std std-term">moved</em></a>.</p>
<p>A typical use is in the implementation of a hash table which
hashes blocks by hashing their addresses. After a block has moved,
the table needs to be rehashed, otherwise it will not be
found in the table.</p>
</dd></dl>
<dl class="type">
<dt id="mps_ld_s">
<tt class="descname">mps_ld_s</tt><a class="headerlink" href="#mps_ld_s" title="Permalink to this definition"></a></dt>
<dd><p>The type of the structure used to represent a <a class="reference internal" href="../glossary/l.html#term-location-dependency"><em class="xref std std-term">location
dependency</em></a>.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">mps_ld_s</span> <span class="p">{</span>
<span class="n">mps_word_t</span> <span class="n">w0</span><span class="p">,</span> <span class="n">w1</span><span class="p">;</span>
<span class="p">}</span> <span class="n">mps_ld_s</span><span class="p">;</span>
</pre></div>
</div>
<p>It is an opaque structure type: it is supplied so that the
<a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> can inline the structure (because its size
is known), but the client must not access it other than via the
functions <a class="reference internal" href="#mps_ld_add" title="mps_ld_add"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_add()</span></tt></a>, <a class="reference internal" href="#mps_ld_isstale" title="mps_ld_isstale"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_isstale()</span></tt></a>,
<a class="reference internal" href="#mps_ld_merge" title="mps_ld_merge"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_merge()</span></tt></a>, and <a class="reference internal" href="#mps_ld_reset" title="mps_ld_reset"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_reset()</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="mps_ld_add">
void <tt class="descname">mps_ld_add</tt><big>(</big><a class="reference internal" href="#mps_ld_t" title="mps_ld_t">mps_ld_t</a><em>&nbsp;ld</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;addr</em><big>)</big><a class="headerlink" href="#mps_ld_add" title="Permalink to this definition"></a></dt>
<dd><p>Add a dependency on a <a class="reference internal" href="../glossary/b.html#term-block"><em class="xref std std-term">block</em></a> to a <a class="reference internal" href="../glossary/l.html#term-location-dependency"><em class="xref std std-term">location
dependency</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">ld</span></tt> is a location dependency.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> to which <tt class="docutils literal"><span class="pre">addr</span></tt> belongs.</p>
<p><tt class="docutils literal"><span class="pre">addr</span></tt> is the address of the block.</p>
<p>After calling <a class="reference internal" href="#mps_ld_add" title="mps_ld_add"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_add()</span></tt></a>, and until <tt class="docutils literal"><span class="pre">ld</span></tt> is passed to
<a class="reference internal" href="#mps_ld_reset" title="mps_ld_reset"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_reset()</span></tt></a>, the call</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_ld_isstale</span><span class="p">(</span><span class="n">ld</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">addr</span><span class="p">)</span>
</pre></div>
</div>
<p>will return true if the block has moved.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p>It is an error to call <a class="reference internal" href="#mps_ld_add" title="mps_ld_add"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_add()</span></tt></a> on the same
location dependency with addresses from two different arenas.
If you need to test for staleness against multiple arenas,
then you need at least one location dependency for each arena.</p>
<p class="last"><a class="reference internal" href="#mps_ld_add" title="mps_ld_add"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_add()</span></tt></a> is not thread-safe with respect to
<a class="reference internal" href="#mps_ld_add" title="mps_ld_add"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_add()</span></tt></a>, <a class="reference internal" href="#mps_ld_merge" title="mps_ld_merge"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_merge()</span></tt></a>, or
<a class="reference internal" href="#mps_ld_reset" title="mps_ld_reset"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_reset()</span></tt></a> on the same location dependency, but it
is thread-safe with respect to <a class="reference internal" href="#mps_ld_isstale" title="mps_ld_isstale"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_isstale()</span></tt></a>
operations. This means that calls to <a class="reference internal" href="#mps_ld_add" title="mps_ld_add"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_add()</span></tt></a> from
different <a class="reference internal" href="../glossary/t.html#term-thread"><em class="xref std std-term">threads</em></a> must interlock if they are
using the same location dependency. The practical upshot of
this is that there should be a lock associated with each
location dependency.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_ld_isstale">
<a class="reference internal" href="interface.html#mps_bool_t" title="mps_bool_t">mps_bool_t</a> <tt class="descname">mps_ld_isstale</tt><big>(</big><a class="reference internal" href="#mps_ld_t" title="mps_ld_t">mps_ld_t</a><em>&nbsp;ld</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;addr</em><big>)</big><a class="headerlink" href="#mps_ld_isstale" title="Permalink to this definition"></a></dt>
<dd><p>Determine if any of the dependencies in a <a class="reference internal" href="../glossary/l.html#term-location-dependency"><em class="xref std std-term">location
dependency</em></a> are stale with respect to an <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">ld</span></tt> is the location dependency.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena to test for staleness against. It must be
the same arena that was passed to all calls to
<a class="reference internal" href="#mps_ld_add" title="mps_ld_add"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_add()</span></tt></a> on <tt class="docutils literal"><span class="pre">ld</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">addr</span></tt> is an address that may appear in <a class="reference internal" href="../glossary/t.html#term-telemetry-stream"><em class="xref std std-term">telemetry</em></a> events related to this call (it will <em>not</em> be
tested for staleness).</p>
<p>The location dependency is examined to determine whether any of
the dependencies encapsulated in it have been made stale with
respect to <tt class="docutils literal"><span class="pre">arena</span></tt>. If any of the dependencies encapsulated in
the location dependency are stale (that is, the blocks whose
location has been depended on have been moved by <tt class="docutils literal"><span class="pre">arena</span></tt>) then
<a class="reference internal" href="#mps_ld_isstale" title="mps_ld_isstale"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_isstale()</span></tt></a> will return true. If there have been no
calls to <a class="reference internal" href="#mps_ld_add" title="mps_ld_add"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_add()</span></tt></a> on <tt class="docutils literal"><span class="pre">ld</span></tt> since the last call to
<a class="reference internal" href="#mps_ld_reset" title="mps_ld_reset"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_reset()</span></tt></a>, then <a class="reference internal" href="#mps_ld_isstale" title="mps_ld_isstale"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_isstale()</span></tt></a> will return
false. <a class="reference internal" href="#mps_ld_isstale" title="mps_ld_isstale"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_isstale()</span></tt></a> may return any value in other
circumstances (but will strive to return false if the blocks
encapsulated in the location dependency have not moved).</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p><a class="reference internal" href="#mps_ld_isstale" title="mps_ld_isstale"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_isstale()</span></tt></a> may report a false positive
(returning true despite none of the added addresses having
being moved by the arena) but never a false negative
(returning false when an added address has been moved).</p>
<p class="last"><a class="reference internal" href="#mps_ld_isstale" title="mps_ld_isstale"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_isstale()</span></tt></a> is thread-safe with respect to itself
and with respect to <a class="reference internal" href="#mps_ld_add" title="mps_ld_add"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_add()</span></tt></a>, but not with respect
to <a class="reference internal" href="#mps_ld_reset" title="mps_ld_reset"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_reset()</span></tt></a>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_ld_merge">
void <tt class="descname">mps_ld_merge</tt><big>(</big><a class="reference internal" href="#mps_ld_t" title="mps_ld_t">mps_ld_t</a><em>&nbsp;dest_ld</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="#mps_ld_t" title="mps_ld_t">mps_ld_t</a><em>&nbsp;src_ld</em><big>)</big><a class="headerlink" href="#mps_ld_merge" title="Permalink to this definition"></a></dt>
<dd><p>Merge one <a class="reference internal" href="../glossary/l.html#term-location-dependency"><em class="xref std std-term">location dependency</em></a> into another.</p>
<p><tt class="docutils literal"><span class="pre">dest_ld</span></tt> is the destination of the merge.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> .</p>
<p><tt class="docutils literal"><span class="pre">src_ld</span></tt> is the source of the merge.</p>
<p>The effect of this is to add all the addresses that were added to
<tt class="docutils literal"><span class="pre">src_ld</span></tt> to the <tt class="docutils literal"><span class="pre">dest_ld</span></tt>.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="#mps_ld_merge" title="mps_ld_merge"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_merge()</span></tt></a> has the same thread-safety properties
as <a class="reference internal" href="#mps_ld_add" title="mps_ld_add"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_add()</span></tt></a>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_ld_reset">
void <tt class="descname">mps_ld_reset</tt><big>(</big><a class="reference internal" href="#mps_ld_t" title="mps_ld_t">mps_ld_t</a><em>&nbsp;ld</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_ld_reset" title="Permalink to this definition"></a></dt>
<dd><p>Reset a <a class="reference internal" href="../glossary/l.html#term-location-dependency"><em class="xref std std-term">location dependency</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">ld</span></tt> is the location dependency.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is an arena.</p>
<p>After this call, <tt class="docutils literal"><span class="pre">ld</span></tt> encapsulates no dependencies. After the
call to <a class="reference internal" href="#mps_ld_reset" title="mps_ld_reset"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_reset()</span></tt></a> and prior to any call to
<a class="reference internal" href="#mps_ld_add" title="mps_ld_add"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_add()</span></tt></a> on <tt class="docutils literal"><span class="pre">ld</span></tt>, <a class="reference internal" href="#mps_ld_isstale" title="mps_ld_isstale"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_isstale()</span></tt></a> on <tt class="docutils literal"><span class="pre">ld</span></tt>
will return false for all arenas.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="#mps_ld_reset" title="mps_ld_reset"><tt class="xref c c-func docutils literal"><span class="pre">mps_ld_reset()</span></tt></a> is not thread-safe with respect to any
other location dependency function.</p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/logo.png" alt="Logo"/>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">14. Location dependency</a><ul>
<li><a class="reference internal" href="#terminology">14.1. Terminology</a></li>
<li><a class="reference internal" href="#creating-dependencies">14.2. Creating dependencies</a></li>
<li><a class="reference internal" href="#adding-dependencies">14.3. Adding dependencies</a></li>
<li><a class="reference internal" href="#testing-dependencies-for-staleness">14.4. Testing dependencies for staleness</a></li>
<li><a class="reference internal" href="#thread-safety">14.5. Thread safety</a></li>
<li><a class="reference internal" href="#location-dependency-interface">14.6. Location dependency interface</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="finalization.html"
title="previous chapter">13. Finalization</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="cache.html"
title="next chapter">15. Segregated allocation caches</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
<a href="http://www.ravenbrook.com/project/mps/release/">All MPS Kit releases</a>
</p>
<h4>Issues</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/issue/?action=list&amp;view=status%3dopen&amp;display=Job:Priority:Title&amp;sort=Priority">Known issues</a><br>
<a href="http://www.ravenbrook.com/project/mps/issue/?action=fixed&release_fixed=1.111.0">Issues fixed in release 1.111.0</a>
</p><h4>Contact us</h4>
<p class="topless"><a href="mailto:mps-questions@ravenbrook.com">mps-questions@ravenbrook.com</a></p>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="cache.html" title="15. Segregated allocation caches"
>next</a> |</li>
<li class="right" >
<a href="finalization.html" title="13. Finalization"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">Copyright</a> 2013, Ravenbrook Limited.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
Reference in a new issue View git blame Copy permalink