mirror of
git://git.sv.gnu.org/emacs.git
synced 2025-12-28 00:01:33 -08:00
28419106ca
Check in HTML version of the manual (writable on client) so that it will display automatically on the Ravenbrook server and so that we can easily include it in product releases. Copied from Perforce Change: 180338 ServerID: perforce.ravenbrook.com
400 lines
No EOL
35 KiB
HTML
400 lines
No EOL
35 KiB
HTML
|
|
|
|
<!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>13. Location dependency — 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="14. Segregated allocation caches" href="cache.html" />
|
|
<link rel="prev" title="12. 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="14. Segregated allocation caches"
|
|
accesskey="N">next</a> |</li>
|
|
<li class="right" >
|
|
<a href="finalization.html" title="12. Finalization"
|
|
accesskey="P">previous</a> |</li>
|
|
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> »</li>
|
|
<li><a href="index.html" accesskey="U">Reference</a> »</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>13. 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>13.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
|
|
“bit-pattern”) 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>13.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’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>13.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>13.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’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">-></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">&&</span> <span class="n">b</span><span class="o">-></span><span class="n">key</span> <span class="o">!=</span> <span class="nb">NULL</span> <span class="o">&&</span> <span class="n">b</span><span class="o">-></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">-></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">&</span><span class="n">tbl</span><span class="o">-></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">-></span><span class="n">table</span><span class="p">.</span><span class="n">buckets</span><span class="o">-></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">-></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’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>13.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>13.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> ld</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em> arena</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em> 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> ld</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em> arena</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em> 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 depdencies 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> dest_ld</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em> arena</em>, <a class="reference internal" href="#mps_ld_t" title="mps_ld_t">mps_ld_t</a><em> 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> ld</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em> 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="#">13. Location dependency</a><ul>
|
|
<li><a class="reference internal" href="#terminology">13.1. Terminology</a></li>
|
|
<li><a class="reference internal" href="#creating-dependencies">13.2. Creating dependencies</a></li>
|
|
<li><a class="reference internal" href="#adding-dependencies">13.3. Adding dependencies</a></li>
|
|
<li><a class="reference internal" href="#testing-dependencies-for-staleness">13.4. Testing dependencies for staleness</a></li>
|
|
<li><a class="reference internal" href="#thread-safety">13.5. Thread safety</a></li>
|
|
<li><a class="reference internal" href="#location-dependency-interface">13.6. Location dependency interface</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h4>Previous topic</h4>
|
|
<p class="topless"><a href="finalization.html"
|
|
title="previous chapter">12. Finalization</a></p>
|
|
<h4>Next topic</h4>
|
|
<p class="topless"><a href="cache.html"
|
|
title="next chapter">14. Segregated allocation caches</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="14. Segregated allocation caches"
|
|
>next</a> |</li>
|
|
<li class="right" >
|
|
<a href="finalization.html" title="12. Finalization"
|
|
>previous</a> |</li>
|
|
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> »</li>
|
|
<li><a href="index.html" >Reference</a> »</li>
|
|
</ul>
|
|
</div>
|
|
<div class="footer">
|
|
© <a href="../copyright.html">Copyright</a> 2012, Ravenbrook Limited.
|
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
|
|
</div>
|
|
</body>
|
|
</html> |