mirror of
git://git.sv.gnu.org/emacs.git
synced 2025-12-27 07:41:28 -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
644 lines
No EOL
64 KiB
HTML
644 lines
No EOL
64 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>9. Roots — 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="10. Garbage collection" href="collection.html" />
|
|
<link rel="prev" title="8. Threads" href="thread.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="collection.html" title="10. Garbage collection"
|
|
accesskey="N">next</a> |</li>
|
|
<li class="right" >
|
|
<a href="thread.html" title="8. Threads"
|
|
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="roots">
|
|
<span id="topic-root"></span><span id="index-0"></span><h1>9. Roots<a class="headerlink" href="#roots" title="Permalink to this headline">¶</a></h1>
|
|
<p><a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">Roots</em></a> tell the <a class="reference internal" href="../glossary/g.html#term-garbage-collector"><em class="xref std std-term">garbage collector</em></a> where to start
|
|
<a class="reference internal" href="../glossary/t.html#term-trace"><em class="xref std std-term">tracing</em></a>. The garbage collector determines which blocks
|
|
are <a class="reference internal" href="../glossary/r.html#term-reachable"><em class="xref std std-term">reachable</em></a> from the roots, and (in <a class="reference internal" href="../glossary/a.html#term-automatic-memory-management"><em class="xref std std-term">automatically
|
|
managed</em></a> <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pools</em></a>) reclaims
|
|
the <a class="reference internal" href="../glossary/u.html#term-unreachable"><em class="xref std std-term">unreachable</em></a> blocks. This is quite efficient and can be a
|
|
very good approximation to <a class="reference internal" href="../glossary/l.html#term-live"><em class="xref std std-term">liveness</em></a>.</p>
|
|
<p>It is therefore important that all <a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">references</em></a> that the
|
|
<a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> can directly access are registered as roots,
|
|
otherwise the garbage collector might recycle an object that would be
|
|
used in the future. Some collectors, for example Boehm’s, assume that
|
|
all references stored in static data are roots; the Memory Pool System
|
|
is more flexible, but requires the client program to declare which
|
|
references are roots.</p>
|
|
<div class="section" id="registering-roots">
|
|
<span id="index-1"></span><h2>9.1. Registering roots<a class="headerlink" href="#registering-roots" title="Permalink to this headline">¶</a></h2>
|
|
<p>You can register a root at any time by calling one of the
|
|
<tt class="docutils literal"><span class="pre">mps_root_create</span></tt> functions. Roots may not be regstered twice, and
|
|
no two roots may overlap (that is, each reference is <a class="reference internal" href="../glossary/f.html#term-fix"><em class="xref std std-term">fixed</em></a> by
|
|
at most one root). Roots may be:</p>
|
|
<ol class="arabic simple">
|
|
<li>on the program’s <a class="reference internal" href="../glossary/c.html#term-control-stack"><em class="xref std std-term">control stack</em></a>;</li>
|
|
<li>in the program’s static data;</li>
|
|
<li>in <a class="reference internal" href="../glossary/h.html#term-heap"><em class="xref std std-term">heap</em></a> not managed by the MPS (provided that you destroy
|
|
the root before freeing it; see <a class="reference internal" href="../guide/lang.html#guide-lang-roots-rehash"><em>the Scheme interpreter’s
|
|
global symbol table</em></a> for an example);</li>
|
|
<li>in <a class="reference internal" href="../glossary/m.html#term-manual-memory-management"><em class="xref std std-term">manually managed</em></a> pools
|
|
(provided that you remove the root before freeing it).</li>
|
|
</ol>
|
|
<p>Roots must not be in memory that is subject to <a class="reference internal" href="../glossary/g.html#term-garbage-collection"><em class="xref std std-term">garbage
|
|
collection</em></a> (and so roots must not be in <a class="reference internal" href="../glossary/a.html#term-automatic-memory-management"><em class="xref std std-term">automatically managed</em></a> pools).</p>
|
|
<p>When you register a root you describe to the MPS how to <a class="reference internal" href="../glossary/s.html#term-scan"><em class="xref std std-term">scan</em></a>
|
|
it for references, providing your own scanning function in the cases
|
|
of <a class="reference internal" href="#mps_root_create" title="mps_root_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create()</span></tt></a> and <a class="reference internal" href="#mps_root_create_fmt" title="mps_root_create_fmt"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create_fmt()</span></tt></a>. Such a
|
|
root scanning function must follow the <a class="reference internal" href="scanning.html#topic-scanning-protocol"><em>Scanning protocol</em></a>.</p>
|
|
<p>All the references in a root are of the same <a class="reference internal" href="../glossary/r.html#term-rank"><em class="xref std std-term">rank</em></a> (just as in
|
|
a <a class="reference internal" href="../glossary/f.html#term-formatted-object"><em class="xref std std-term">formatted object</em></a>). So they are all <a class="reference internal" href="../glossary/e.html#term-exact-reference"><em class="xref std std-term">exact</em></a>, <a class="reference internal" href="../glossary/a.html#term-ambiguous-reference"><em class="xref std std-term">ambiguous</em></a> or <a class="reference internal" href="../glossary/w.html#term-weak-reference-1"><em class="xref std std-term">weak</em></a>.</p>
|
|
<div class="admonition-note admonition">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">If the rank of the root is <a class="reference internal" href="../glossary/e.html#term-exact-reference"><em class="xref std std-term">exact</em></a>, or
|
|
<a class="reference internal" href="../glossary/w.html#term-weak-reference-1"><em class="xref std std-term">weak</em></a>, the references in the root must
|
|
always be valid while the root is registered: that is, they must
|
|
be references to actual objects or null pointers. This could be
|
|
immediately after the root is registered, so the root must be
|
|
valid before it is registered.</p>
|
|
</div>
|
|
<div class="admonition-note admonition">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">As with <a class="reference internal" href="scanning.html#topic-scanning"><em>scanning</em></a> in general, it’s safe to
|
|
<a class="reference internal" href="../glossary/f.html#term-fix"><em class="xref std std-term">fix</em></a> references that point to memory not managed by the
|
|
MPS. These will be ignored.</p>
|
|
</div>
|
|
<p>Roots can be deregistered at any time by calling
|
|
<a class="reference internal" href="#mps_root_destroy" title="mps_root_destroy"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_destroy()</span></tt></a>. All roots registered in an <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a>
|
|
must be deregistered before the arena is destroyed.</p>
|
|
<p>There are five ways to register a root, depending on how you need to
|
|
scan it for references:</p>
|
|
<ol class="arabic simple">
|
|
<li><a class="reference internal" href="#mps_root_create" title="mps_root_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create()</span></tt></a> if you need a custom root scanning
|
|
function (of type <a class="reference internal" href="#mps_root_scan_t" title="mps_root_scan_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_root_scan_t</span></tt></a>);</li>
|
|
<li><a class="reference internal" href="#mps_root_create_fmt" title="mps_root_create_fmt"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create_fmt()</span></tt></a> if the root consists of a block of
|
|
objects belonging to an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>, which can be scanned
|
|
by the format’s <a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan method</em></a> (of type
|
|
<a class="reference internal" href="format.html#mps_fmt_scan_t" title="mps_fmt_scan_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_scan_t</span></tt></a>);</li>
|
|
<li><a class="reference internal" href="#mps_root_create_table" title="mps_root_create_table"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create_table()</span></tt></a> if the root consists of a table of
|
|
references;</li>
|
|
<li><a class="reference internal" href="#mps_root_create_table_masked" title="mps_root_create_table_masked"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create_table_masked()</span></tt></a> if the root consists of a
|
|
table of <a class="reference internal" href="../glossary/t.html#term-tagged-reference"><em class="xref std std-term">tagged references</em></a>;</li>
|
|
<li><a class="reference internal" href="#mps_root_create_reg" title="mps_root_create_reg"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create_reg()</span></tt></a> if the root consists of the
|
|
registers and control stack of a thread. See
|
|
<a class="reference internal" href="#topic-root-thread"><em>Thread roots</em></a> below.</li>
|
|
</ol>
|
|
</div>
|
|
<div class="section" id="cautions">
|
|
<span id="index-2"></span><h2>9.2. Cautions<a class="headerlink" href="#cautions" title="Permalink to this headline">¶</a></h2>
|
|
<p>Creating a root and then registering is similar to reserving a block
|
|
and then committing it (in the
|
|
<a class="reference internal" href="allocation.html#topic-allocation-point-protocol"><em>Allocation point protocol</em></a>), and similar <a class="reference internal" href="allocation.html#topic-allocation-cautions"><em>cautions</em></a> apply. Before registering a root:</p>
|
|
<ol class="arabic simple">
|
|
<li>The root must be valid (that is, the appropriate root scanning
|
|
function can scan it).</li>
|
|
<li>All <a class="reference internal" href="../glossary/e.html#term-exact-reference"><em class="xref std std-term">exact references</em></a> in the root (references that are
|
|
<a class="reference internal" href="../glossary/f.html#term-fix"><em class="xref std std-term">fixed</em></a> by the root scanning function) must contain valid
|
|
references or null pointers.</li>
|
|
<li>You must not store a reference in the root to a block in an
|
|
automatically managed pool (such a reference is hidden from the MPS
|
|
until you register the root, and may become invalid).</li>
|
|
</ol>
|
|
<p>So the typical sequence of operations when creating a root is:</p>
|
|
<ol class="arabic simple">
|
|
<li>Initialize references in the root with null pointers or other safe
|
|
values.</li>
|
|
<li>Register the root.</li>
|
|
<li>Fill in the references in the root.</li>
|
|
</ol>
|
|
</div>
|
|
<div class="section" id="thread-roots">
|
|
<span id="topic-root-thread"></span><span id="index-3"></span><h2>9.3. Thread roots<a class="headerlink" href="#thread-roots" title="Permalink to this headline">¶</a></h2>
|
|
<p>Every thread’s registers and control stack potentially contain
|
|
references to allocated objects, so should be registered as a root by
|
|
calling <a class="reference internal" href="#mps_root_create_reg" title="mps_root_create_reg"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create_reg()</span></tt></a>. It’s not easy to write a
|
|
scanner for the registers and the stack: it depends on the operating
|
|
system, the processor architecture, and in some cases on the compiler.
|
|
For this reason, the MPS provides <a class="reference internal" href="#mps_stack_scan_ambig" title="mps_stack_scan_ambig"><tt class="xref c c-func docutils literal"><span class="pre">mps_stack_scan_ambig()</span></tt></a> (and
|
|
in fact, this is the only supported stack scanner).</p>
|
|
<p>A stack scanner needs to know how to find the bottom of the part of
|
|
the stack to scan. Now, every thread that runs code that uses memory
|
|
managed by the MPS must execute such code inside the MPS trampoline by
|
|
calling <a class="reference internal" href="thread.html#mps_tramp" title="mps_tramp"><tt class="xref c c-func docutils literal"><span class="pre">mps_tramp()</span></tt></a>. This means that the bottom of the
|
|
relevant part of stack can be found by taking the address of a local
|
|
variable in the function that calls <a class="reference internal" href="thread.html#mps_tramp" title="mps_tramp"><tt class="xref c c-func docutils literal"><span class="pre">mps_tramp()</span></tt></a> (the variable
|
|
<tt class="docutils literal"><span class="pre">marker</span></tt> in the example below).</p>
|
|
<p id="index-4">For example, here’s the code from the toy Scheme interpreter that
|
|
registers a thread root and then trampolines into the program:</p>
|
|
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_thr_t</span> <span class="kr">thread</span><span class="p">;</span>
|
|
<span class="n">mps_root_t</span> <span class="n">reg_root</span><span class="p">;</span>
|
|
<span class="kt">void</span> <span class="o">*</span><span class="n">marker</span> <span class="o">=</span> <span class="o">&</span><span class="n">marker</span><span class="p">;</span>
|
|
<span class="kt">void</span> <span class="o">*</span><span class="n">r</span><span class="p">;</span>
|
|
|
|
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_thread_reg</span><span class="p">(</span><span class="o">&</span><span class="kr">thread</span><span class="p">,</span> <span class="n">arena</span><span class="p">);</span>
|
|
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">"Couldn't register thread"</span><span class="p">);</span>
|
|
|
|
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_root_create_reg</span><span class="p">(</span><span class="o">&</span><span class="n">reg_root</span><span class="p">,</span>
|
|
<span class="n">arena</span><span class="p">,</span>
|
|
<span class="n">mps_rank_ambig</span><span class="p">(),</span>
|
|
<span class="mi">0</span><span class="p">,</span>
|
|
<span class="kr">thread</span><span class="p">,</span>
|
|
<span class="n">mps_stack_scan_ambig</span><span class="p">,</span>
|
|
<span class="n">marker</span><span class="p">,</span>
|
|
<span class="mi">0</span><span class="p">);</span>
|
|
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">"Couldn't create root"</span><span class="p">);</span>
|
|
|
|
<span class="n">mps_tramp</span><span class="p">(</span><span class="o">&</span><span class="n">r</span><span class="p">,</span> <span class="n">start</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="ranks">
|
|
<span id="index-5"></span><h2>9.4. Ranks<a class="headerlink" href="#ranks" title="Permalink to this headline">¶</a></h2>
|
|
<dl class="type">
|
|
<dt id="mps_rank_t">
|
|
<tt class="descname">mps_rank_t</tt><a class="headerlink" href="#mps_rank_t" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>The type of <a class="reference internal" href="../glossary/r.html#term-rank"><em class="xref std std-term">ranks</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 <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">int</span></tt>, provided for convenience
|
|
and clarity.</p>
|
|
</dd></dl>
|
|
|
|
<dl class="function">
|
|
<dt id="mps_rank_ambig">
|
|
<a class="reference internal" href="#mps_rank_t" title="mps_rank_t">mps_rank_t</a> <tt class="descname">mps_rank_ambig</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_rank_ambig" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>Return the <a class="reference internal" href="../glossary/r.html#term-rank"><em class="xref std std-term">rank</em></a> of <a class="reference internal" href="../glossary/a.html#term-ambiguous-root"><em class="xref std std-term">ambiguous roots</em></a>.</p>
|
|
</dd></dl>
|
|
|
|
<dl class="function">
|
|
<dt id="mps_rank_exact">
|
|
<a class="reference internal" href="#mps_rank_t" title="mps_rank_t">mps_rank_t</a> <tt class="descname">mps_rank_exact</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_rank_exact" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>Return the <a class="reference internal" href="../glossary/r.html#term-rank"><em class="xref std std-term">rank</em></a> of <a class="reference internal" href="../glossary/e.html#term-exact-root"><em class="xref std std-term">exact roots</em></a>.</p>
|
|
</dd></dl>
|
|
|
|
<dl class="function">
|
|
<dt id="mps_rank_weak">
|
|
<a class="reference internal" href="#mps_rank_t" title="mps_rank_t">mps_rank_t</a> <tt class="descname">mps_rank_weak</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_rank_weak" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>Return the <a class="reference internal" href="../glossary/r.html#term-rank"><em class="xref std std-term">rank</em></a> of <a class="reference internal" href="../glossary/w.html#term-weak-root"><em class="xref std std-term">weak roots</em></a>.</p>
|
|
</dd></dl>
|
|
|
|
</div>
|
|
<div class="section" id="root-modes">
|
|
<span id="index-6"></span><h2>9.5. Root modes<a class="headerlink" href="#root-modes" title="Permalink to this headline">¶</a></h2>
|
|
<p>The root mode provides a way for the client to declare various facts
|
|
about a root that allow the MPS to make optimizations. Roots that are
|
|
declared to be <em>constant</em> need not be re-scanned, and roots that are
|
|
declared to be <em>protectable</em> may have barriers placed on them,
|
|
allowing the MPS to detect whether they have changed.</p>
|
|
<div class="admonition-note admonition">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">The MPS does not currently perform either of these optimizations,
|
|
so root modes have no effect. These features may be added in a
|
|
future release.</p>
|
|
</div>
|
|
<dl class="type">
|
|
<dt id="mps_rm_t">
|
|
<tt class="descname">mps_rm_t</tt><a class="headerlink" href="#mps_rm_t" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>The type of <a class="reference internal" href="../glossary/r.html#term-root-mode"><em class="xref std std-term">root modes</em></a>.</p>
|
|
<p>It should be zero (meaning neither constant or protectable), or
|
|
the sum of some subset of <a class="reference internal" href="#MPS_RM_CONST" title="MPS_RM_CONST"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RM_CONST</span></tt></a> and
|
|
<a class="reference internal" href="#MPS_RM_PROT" title="MPS_RM_PROT"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RM_PROT</span></tt></a>.</p>
|
|
</dd></dl>
|
|
|
|
<dl class="macro">
|
|
<dt id="MPS_RM_CONST">
|
|
<tt class="descname">MPS_RM_CONST</tt><a class="headerlink" href="#MPS_RM_CONST" title="Permalink to this definition">¶</a></dt>
|
|
<dd><div class="admonition-deprecated admonition">
|
|
<p class="first admonition-title">Deprecated</p>
|
|
<p>starting with version 1.111.</p>
|
|
<p class="last">This was introduced in the hope of being able to maintain a
|
|
<a class="reference internal" href="../glossary/r.html#term-remembered-set"><em class="xref std std-term">remembered set</em></a> for the root without needing a
|
|
<a class="reference internal" href="../glossary/w.html#term-write-barrier"><em class="xref std std-term">write barrier</em></a>, but it can’t work as described, since
|
|
you can’t reliably a valid registered constant root that
|
|
contains any references. (If you add the references before
|
|
registering the root, they may have become invalid; but you
|
|
can’t add them afterwards because the root is supposed to be
|
|
constant.)</p>
|
|
</div>
|
|
<p>The <a class="reference internal" href="../glossary/r.html#term-root-mode"><em class="xref std std-term">root mode</em></a> for <a class="reference internal" href="../glossary/c.html#term-constant-root"><em class="xref std std-term">constant roots</em></a>.
|
|
This tells the MPS that the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> will not change
|
|
the <a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">root</em></a> after it is registered: that is, scanning the
|
|
root will produce the same set of <a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">references</em></a>
|
|
every time. Furthermore, for roots registered by
|
|
<a class="reference internal" href="#mps_root_create_fmt" title="mps_root_create_fmt"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create_fmt()</span></tt></a> and <a class="reference internal" href="#mps_root_create_table" title="mps_root_create_table"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create_table()</span></tt></a>,
|
|
the client program will not write to the root at all.</p>
|
|
</dd></dl>
|
|
|
|
<dl class="macro">
|
|
<dt id="MPS_RM_PROT">
|
|
<tt class="descname">MPS_RM_PROT</tt><a class="headerlink" href="#MPS_RM_PROT" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>The <a class="reference internal" href="../glossary/r.html#term-root-mode"><em class="xref std std-term">root mode</em></a> for <a class="reference internal" href="../glossary/p.html#term-protectable-root"><em class="xref std std-term">protectable roots</em></a>. This tells
|
|
the MPS that it may place a <a class="reference internal" href="../glossary/b.html#term-barrier-1"><em class="xref std std-term">barrier<sup>(1)</sup></em></a> on any
|
|
<a class="reference internal" href="../glossary/p.html#term-page"><em class="xref std std-term">page</em></a> which any part of the <a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">root</em></a> covers. No
|
|
<a class="reference internal" href="../glossary/f.html#term-format-method"><em class="xref std std-term">format method</em></a> or <a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan method</em></a> (except for the one
|
|
for this root) may write data in this root. They may read it.</p>
|
|
<div class="admonition-note admonition">
|
|
<p class="first admonition-title">Note</p>
|
|
<p>You must not specify <tt class="docutils literal"><span class="pre">MPS_RM_PROT</span></tt> on a root allocated by
|
|
the MPS.</p>
|
|
<p>No page may contain parts of two or more protectable roots.
|
|
You mustn’t specify <tt class="docutils literal"><span class="pre">MPS_RM_PROT</span></tt> if the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client
|
|
program</em></a> or anything other than (this instance of) the MPS is
|
|
going to protect or unprotect the relevant pages.</p>
|
|
<p class="last">This mode may not be suitable if the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a>
|
|
wants the operating system to be able to access the root. Many
|
|
operating systems can’t cope with writing to protected pages.</p>
|
|
</div>
|
|
</dd></dl>
|
|
|
|
</div>
|
|
<div class="section" id="root-interface">
|
|
<span id="index-7"></span><h2>9.6. Root interface<a class="headerlink" href="#root-interface" title="Permalink to this headline">¶</a></h2>
|
|
<dl class="type">
|
|
<dt id="mps_root_t">
|
|
<tt class="descname">mps_root_t</tt><a class="headerlink" href="#mps_root_t" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>The type of <a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">root</em></a> descriptions.</p>
|
|
<p>The <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> uses root descriptions to find
|
|
<a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">references</em></a> within the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program’s</em></a> roots.</p>
|
|
</dd></dl>
|
|
|
|
<dl class="function">
|
|
<dt id="mps_root_create">
|
|
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_root_create</tt><big>(</big><a class="reference internal" href="#mps_root_t" title="mps_root_t">mps_root_t</a><em> *root_o</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_rank_t" title="mps_rank_t">mps_rank_t</a><em> rank</em>, <a class="reference internal" href="#mps_rm_t" title="mps_rm_t">mps_rm_t</a><em> rm</em>, <a class="reference internal" href="#mps_root_scan_t" title="mps_root_scan_t">mps_root_scan_t</a><em> root_scan</em>, void<em> *p</em>, size_t<em> s</em><big>)</big><a class="headerlink" href="#mps_root_create" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>Register a <a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">root</em></a> that consists of the <a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">references</em></a> fixed by a scanning function.</p>
|
|
<p><tt class="docutils literal"><span class="pre">root_o</span></tt> points to a location that will hold the address of the
|
|
new root description.</p>
|
|
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena.</p>
|
|
<p><tt class="docutils literal"><span class="pre">rank</span></tt> is the <a class="reference internal" href="../glossary/r.html#term-rank"><em class="xref std std-term">rank</em></a> of references in the root.</p>
|
|
<p><tt class="docutils literal"><span class="pre">rm</span></tt> is the <a class="reference internal" href="../glossary/r.html#term-root-mode"><em class="xref std std-term">root mode</em></a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">root_scan</span></tt> is the root scanning function. See
|
|
<a class="reference internal" href="#mps_root_scan_t" title="mps_root_scan_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_root_scan_t</span></tt></a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">p</span></tt> and <tt class="docutils literal"><span class="pre">s</span></tt> are arguments that will be passed to <tt class="docutils literal"><span class="pre">root_scan</span></tt> each
|
|
time it is called. This is intended to make it easy to pass, for
|
|
example, an array and its size as parameters.</p>
|
|
<p>Returns <a class="reference internal" href="error.html#MPS_RES_OK" title="MPS_RES_OK"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_OK</span></tt></a> if the root was registered
|
|
successfully, <a class="reference internal" href="error.html#MPS_RES_MEMORY" title="MPS_RES_MEMORY"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_MEMORY</span></tt></a> if the new root
|
|
description could not be allocated, or another <a class="reference internal" href="../glossary/r.html#term-result-code"><em class="xref std std-term">result code</em></a>
|
|
if there was another error.</p>
|
|
<p>The registered root destription persists until it is destroyed by
|
|
calling <a class="reference internal" href="#mps_root_destroy" title="mps_root_destroy"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_destroy()</span></tt></a>.</p>
|
|
</dd></dl>
|
|
|
|
<dl class="type">
|
|
<dt id="mps_root_scan_t">
|
|
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">(*mps_root_scan_t)</tt><big>(</big><a class="reference internal" href="scanning.html#mps_ss_t" title="mps_ss_t">mps_ss_t</a><em> ss</em>, void<em> *p</em>, size_t<em> s</em><big>)</big><a class="headerlink" href="#mps_root_scan_t" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>The type of root scanning functions for <a class="reference internal" href="#mps_root_create" title="mps_root_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create()</span></tt></a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">ss</span></tt> is the <a class="reference internal" href="../glossary/s.html#term-scan-state"><em class="xref std std-term">scan state</em></a>. It must be passed to
|
|
<a class="reference internal" href="scanning.html#MPS_SCAN_BEGIN" title="MPS_SCAN_BEGIN"><tt class="xref c c-func docutils literal"><span class="pre">MPS_SCAN_BEGIN()</span></tt></a> and <a class="reference internal" href="scanning.html#MPS_SCAN_END" title="MPS_SCAN_END"><tt class="xref c c-func docutils literal"><span class="pre">MPS_SCAN_END()</span></tt></a> to delimit a
|
|
sequence of fix operations, and to the functions
|
|
<a class="reference internal" href="scanning.html#MPS_FIX1" title="MPS_FIX1"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX1()</span></tt></a> and <a class="reference internal" href="scanning.html#MPS_FIX2" title="MPS_FIX2"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX2()</span></tt></a> when fixing a
|
|
<a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">reference</em></a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">p</span></tt> and <tt class="docutils literal"><span class="pre">s</span></tt> are the corresponding values that were passed to
|
|
<a class="reference internal" href="#mps_root_create" title="mps_root_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create()</span></tt></a>.</p>
|
|
<p>Returns a <a class="reference internal" href="../glossary/r.html#term-result-code"><em class="xref std std-term">result code</em></a>. If a fix function returns a value
|
|
other than <a class="reference internal" href="error.html#MPS_RES_OK" title="MPS_RES_OK"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_OK</span></tt></a>, the scan method must return that
|
|
value, and may return without fixing any further references.
|
|
Generally, itis better if it returns as soon as possible. If the
|
|
scanning is completed successfully, the function should return
|
|
<a class="reference internal" href="error.html#MPS_RES_OK" title="MPS_RES_OK"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_OK</span></tt></a>.</p>
|
|
</dd></dl>
|
|
|
|
<dl class="function">
|
|
<dt id="mps_root_create_fmt">
|
|
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_root_create_fmt</tt><big>(</big><a class="reference internal" href="#mps_root_t" title="mps_root_t">mps_root_t</a><em> *root_o</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_rank_t" title="mps_rank_t">mps_rank_t</a><em> rank</em>, <a class="reference internal" href="#mps_rm_t" title="mps_rm_t">mps_rm_t</a><em> rm</em>, <a class="reference internal" href="format.html#mps_fmt_scan_t" title="mps_fmt_scan_t">mps_fmt_scan_t</a><em> fmt_scan</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em> base</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em> limit</em><big>)</big><a class="headerlink" href="#mps_root_create_fmt" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>Register a <a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">root</em></a> that consists of the <a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">references</em></a> fixed by a scanning function in a block of
|
|
<a class="reference internal" href="../glossary/f.html#term-formatted-object"><em class="xref std std-term">formatted objects</em></a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">root_o</span></tt> points to a location that will hold the address of the
|
|
new root description.</p>
|
|
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena.</p>
|
|
<p><tt class="docutils literal"><span class="pre">rank</span></tt> is the <a class="reference internal" href="../glossary/r.html#term-rank"><em class="xref std std-term">rank</em></a> of references in the root.</p>
|
|
<p><tt class="docutils literal"><span class="pre">rm</span></tt> is the <a class="reference internal" href="../glossary/r.html#term-root-mode"><em class="xref std std-term">root mode</em></a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">fmt_scan</span></tt> is a scanning function. See <a class="reference internal" href="format.html#mps_fmt_scan_t" title="mps_fmt_scan_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_scan_t</span></tt></a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">base</span></tt> is the address of the base of the block of formatted
|
|
objects.</p>
|
|
<p><tt class="docutils literal"><span class="pre">limit</span></tt> is the address just beyond the end of the block of
|
|
formatted objects.</p>
|
|
<p>Returns <a class="reference internal" href="error.html#MPS_RES_OK" title="MPS_RES_OK"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_OK</span></tt></a> if the root was registered
|
|
successfully, <a class="reference internal" href="error.html#MPS_RES_MEMORY" title="MPS_RES_MEMORY"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_MEMORY</span></tt></a> if the new root
|
|
description could not be allocated, or another <a class="reference internal" href="../glossary/r.html#term-result-code"><em class="xref std std-term">result code</em></a>
|
|
if there was another error.</p>
|
|
<p>The registered root destription persists until it is destroyed by
|
|
calling <a class="reference internal" href="#mps_root_destroy" title="mps_root_destroy"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_destroy()</span></tt></a>.</p>
|
|
</dd></dl>
|
|
|
|
<dl class="function">
|
|
<dt id="mps_root_create_reg">
|
|
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_root_create_reg</tt><big>(</big><a class="reference internal" href="#mps_root_t" title="mps_root_t">mps_root_t</a><em> *root_o</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_rank_t" title="mps_rank_t">mps_rank_t</a><em> rank</em>, <a class="reference internal" href="#mps_rm_t" title="mps_rm_t">mps_rm_t</a><em> rm</em>, <a class="reference internal" href="thread.html#mps_thr_t" title="mps_thr_t">mps_thr_t</a><em> thr</em>, <a class="reference internal" href="#mps_reg_scan_t" title="mps_reg_scan_t">mps_reg_scan_t</a><em> reg_scan</em>, void<em> *p</em>, size_t<em> s</em><big>)</big><a class="headerlink" href="#mps_root_create_reg" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>Register a <a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">root</em></a> that consists of the <a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">references</em></a>
|
|
fixed in a <a class="reference internal" href="../glossary/t.html#term-thread"><em class="xref std std-term">thread’s</em></a> stack by a scanning function.</p>
|
|
<p><tt class="docutils literal"><span class="pre">root_o</span></tt> points to a location that will hold the address of the
|
|
new root description.</p>
|
|
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena.</p>
|
|
<p><tt class="docutils literal"><span class="pre">rank</span></tt> is the <a class="reference internal" href="../glossary/r.html#term-rank"><em class="xref std std-term">rank</em></a> of references in the root.</p>
|
|
<p><tt class="docutils literal"><span class="pre">rm</span></tt> is the <a class="reference internal" href="../glossary/r.html#term-root-mode"><em class="xref std std-term">root mode</em></a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">thr</span></tt> is the thread.</p>
|
|
<p><tt class="docutils literal"><span class="pre">reg_scan</span></tt> is a scanning function. See <a class="reference internal" href="#mps_reg_scan_t" title="mps_reg_scan_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_reg_scan_t</span></tt></a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">p</span></tt> and <tt class="docutils literal"><span class="pre">s</span></tt> are arguments that will be passed to <tt class="docutils literal"><span class="pre">reg_scan</span></tt> each
|
|
time it is called. This is intended to make it easy to pass, for
|
|
example, an array and its size as parameters.</p>
|
|
<p>Returns <a class="reference internal" href="error.html#MPS_RES_OK" title="MPS_RES_OK"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_OK</span></tt></a> if the root was registered
|
|
successfully, <a class="reference internal" href="error.html#MPS_RES_MEMORY" title="MPS_RES_MEMORY"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_MEMORY</span></tt></a> if the new root
|
|
description could not be allocated, or another <a class="reference internal" href="../glossary/r.html#term-result-code"><em class="xref std std-term">result code</em></a>
|
|
if there was another error.</p>
|
|
<p>The registered root destription persists until it is destroyed by
|
|
calling <a class="reference internal" href="#mps_root_destroy" title="mps_root_destroy"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_destroy()</span></tt></a>.</p>
|
|
<div class="admonition-note admonition">
|
|
<p class="first admonition-title">Note</p>
|
|
<p>It is not supported for <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client programs</em></a> to pass their
|
|
own scanning functions to this function. The built-in MPS
|
|
function <a class="reference internal" href="#mps_stack_scan_ambig" title="mps_stack_scan_ambig"><tt class="xref c c-func docutils literal"><span class="pre">mps_stack_scan_ambig()</span></tt></a> must be used.</p>
|
|
<p class="last">This function is intended as a hook should we ever need to
|
|
allow client-specific extension or customization of stack and
|
|
register scanning. If you’re in a position where you need
|
|
this, for example, if you’re writing a compiler and have
|
|
control over what goes in the registers, <a class="reference internal" href="../contact.html#contact"><em>contact us</em></a>.</p>
|
|
</div>
|
|
</dd></dl>
|
|
|
|
<dl class="type">
|
|
<dt id="mps_reg_scan_t">
|
|
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">(*mps_reg_scan_t)</tt><big>(</big><a class="reference internal" href="scanning.html#mps_ss_t" title="mps_ss_t">mps_ss_t</a><em> ss</em>, <a class="reference internal" href="thread.html#mps_thr_t" title="mps_thr_t">mps_thr_t</a><em> thr</em>, void<em> *p</em>, size_t<em> s</em><big>)</big><a class="headerlink" href="#mps_reg_scan_t" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>The type of a root scanning function for roots created with
|
|
<a class="reference internal" href="#mps_root_create_reg" title="mps_root_create_reg"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create_reg()</span></tt></a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">ss</span></tt> is the <a class="reference internal" href="../glossary/s.html#term-scan-state"><em class="xref std std-term">scan state</em></a>. It must be passed to
|
|
<a class="reference internal" href="scanning.html#MPS_SCAN_BEGIN" title="MPS_SCAN_BEGIN"><tt class="xref c c-func docutils literal"><span class="pre">MPS_SCAN_BEGIN()</span></tt></a> and <a class="reference internal" href="scanning.html#MPS_SCAN_END" title="MPS_SCAN_END"><tt class="xref c c-func docutils literal"><span class="pre">MPS_SCAN_END()</span></tt></a> to delimit a
|
|
sequence of fix operations, and to the functions
|
|
<a class="reference internal" href="scanning.html#MPS_FIX1" title="MPS_FIX1"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX1()</span></tt></a> and <a class="reference internal" href="scanning.html#MPS_FIX2" title="MPS_FIX2"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX2()</span></tt></a> when fixing a
|
|
<a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">reference</em></a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">thr</span></tt> is the <a class="reference internal" href="../glossary/t.html#term-thread"><em class="xref std std-term">thread</em></a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">p</span></tt> and <tt class="docutils literal"><span class="pre">s</span></tt> are the corresponding values that were passed to
|
|
<a class="reference internal" href="#mps_root_create_reg" title="mps_root_create_reg"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create_reg()</span></tt></a>.</p>
|
|
<p>Returns a <a class="reference internal" href="../glossary/r.html#term-result-code"><em class="xref std std-term">result code</em></a>. If a fix function returns a value
|
|
other than <a class="reference internal" href="error.html#MPS_RES_OK" title="MPS_RES_OK"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_OK</span></tt></a>, the scan method must return that
|
|
value, and may return without fixing any further references.
|
|
Generally, itis better if it returns as soon as possible. If the
|
|
scanning is completed successfully, the function should return
|
|
<a class="reference internal" href="error.html#MPS_RES_OK" title="MPS_RES_OK"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_OK</span></tt></a>.</p>
|
|
<p>A root scan method is called whenever the MPS needs to scan the
|
|
root. It must then indicate references within the root by calling
|
|
<a class="reference internal" href="scanning.html#MPS_FIX1" title="MPS_FIX1"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX1()</span></tt></a> and <a class="reference internal" href="scanning.html#MPS_FIX2" title="MPS_FIX2"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX2()</span></tt></a>.</p>
|
|
<div class="admonition-see-also admonition seealso">
|
|
<p class="first admonition-title">See also</p>
|
|
<p class="last"><a class="reference internal" href="scanning.html#topic-scanning"><em>Scanning</em></a>.</p>
|
|
</div>
|
|
<div class="admonition-note admonition">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last"><a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">Client programs</em></a> are not expected to
|
|
write scanning functions of this type. The built-in MPS
|
|
function <a class="reference internal" href="#mps_stack_scan_ambig" title="mps_stack_scan_ambig"><tt class="xref c c-func docutils literal"><span class="pre">mps_stack_scan_ambig()</span></tt></a> must be used.</p>
|
|
</div>
|
|
</dd></dl>
|
|
|
|
<dl class="function">
|
|
<dt id="mps_stack_scan_ambig">
|
|
<a class="reference internal" href="#mps_reg_scan_t" title="mps_reg_scan_t">mps_reg_scan_t</a> <tt class="descname">mps_stack_scan_ambig</tt><big>(</big><big>)</big><a class="headerlink" href="#mps_stack_scan_ambig" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>A root scanning function for <a class="reference internal" href="../glossary/a.html#term-ambiguous-reference"><em class="xref std std-term">ambiguous</em></a> scanning of <a class="reference internal" href="../glossary/t.html#term-thread"><em class="xref std std-term">threads</em></a>, suitable for
|
|
passing to <a class="reference internal" href="#mps_root_create_reg" title="mps_root_create_reg"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_create_reg()</span></tt></a>.</p>
|
|
<p>It scans all integer registers and everything on the stack of the
|
|
thread given, and can therefore only be used with <a class="reference internal" href="../glossary/a.html#term-ambiguous-root"><em class="xref std std-term">ambiguous
|
|
roots</em></a>. It only scans locations that are at, or higher on the
|
|
stack (that is, more recently added), the stack bottom that was
|
|
passed to <a class="reference internal" href="thread.html#mps_thread_reg" title="mps_thread_reg"><tt class="xref c c-func docutils literal"><span class="pre">mps_thread_reg()</span></tt></a>. References are assumed to be
|
|
represented as machine words, and are required to be
|
|
4-byte-aligned; unaligned values are ignored.</p>
|
|
<div class="admonition-note admonition">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">The MPS provides this function because it’s hard to write: it
|
|
depends on the operating system, the processor architecture,
|
|
and in some cases on the compiler.</p>
|
|
</div>
|
|
</dd></dl>
|
|
|
|
<dl class="function">
|
|
<dt id="mps_root_create_table">
|
|
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_root_create_table</tt><big>(</big><a class="reference internal" href="#mps_root_t" title="mps_root_t">mps_root_t</a><em> *root_o</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_rank_t" title="mps_rank_t">mps_rank_t</a><em> rank</em>, <a class="reference internal" href="#mps_rm_t" title="mps_rm_t">mps_rm_t</a><em> rm</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em> *base</em>, size_t<em> count</em><big>)</big><a class="headerlink" href="#mps_root_create_table" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>Register a <a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">root</em></a> that consists of a vector of
|
|
<a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">references</em></a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">root_o</span></tt> points to a location that will hold the address of the
|
|
new root description.</p>
|
|
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena.</p>
|
|
<p><tt class="docutils literal"><span class="pre">rank</span></tt> is the <a class="reference internal" href="../glossary/r.html#term-rank"><em class="xref std std-term">rank</em></a> of references in the root.</p>
|
|
<p><tt class="docutils literal"><span class="pre">rm</span></tt> is the <a class="reference internal" href="../glossary/r.html#term-root-mode"><em class="xref std std-term">root mode</em></a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">base</span></tt> points to a vector of references.</p>
|
|
<p><tt class="docutils literal"><span class="pre">count</span></tt> is the number of references in the vector.</p>
|
|
<p>Returns <a class="reference internal" href="error.html#MPS_RES_OK" title="MPS_RES_OK"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_OK</span></tt></a> if the root was registered
|
|
successfully, <a class="reference internal" href="error.html#MPS_RES_MEMORY" title="MPS_RES_MEMORY"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_MEMORY</span></tt></a> if the new root
|
|
description could not be allocated, or another <a class="reference internal" href="../glossary/r.html#term-result-code"><em class="xref std std-term">result code</em></a>
|
|
if there was another error.</p>
|
|
<p>The registered root description persists until it is destroyed by
|
|
calling <a class="reference internal" href="#mps_root_destroy" title="mps_root_destroy"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_destroy()</span></tt></a>.</p>
|
|
</dd></dl>
|
|
|
|
<dl class="function">
|
|
<dt id="mps_root_create_table_masked">
|
|
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_root_create_table_masked</tt><big>(</big><a class="reference internal" href="#mps_root_t" title="mps_root_t">mps_root_t</a><em> *root_o</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_rank_t" title="mps_rank_t">mps_rank_t</a><em> rank</em>, <a class="reference internal" href="#mps_rm_t" title="mps_rm_t">mps_rm_t</a><em> rm</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em> *base</em>, size_t<em> count</em>, <a class="reference internal" href="interface.html#mps_word_t" title="mps_word_t">mps_word_t</a><em> mask</em><big>)</big><a class="headerlink" href="#mps_root_create_table_masked" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>Register a <a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">root</em></a> that consists of a vector of <a class="reference internal" href="../glossary/t.html#term-tagged-reference"><em class="xref std std-term">tagged
|
|
references</em></a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">root_o</span></tt> points to a location that will hold the address of the
|
|
new root description.</p>
|
|
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena.</p>
|
|
<p><tt class="docutils literal"><span class="pre">rank</span></tt> is the <a class="reference internal" href="../glossary/r.html#term-rank"><em class="xref std std-term">rank</em></a> of references in the root.</p>
|
|
<p><tt class="docutils literal"><span class="pre">rm</span></tt> is the <a class="reference internal" href="../glossary/r.html#term-root-mode"><em class="xref std std-term">root mode</em></a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">base</span></tt> points to a vector of tagged references.</p>
|
|
<p><tt class="docutils literal"><span class="pre">count</span></tt> is the number of tagged references in the vector.</p>
|
|
<p><tt class="docutils literal"><span class="pre">mask</span></tt> is a <a class="reference internal" href="../glossary/b.html#term-bitmask"><em class="xref std std-term">bitmask</em></a> whose set bits specify the location of
|
|
the <a class="reference internal" href="../glossary/t.html#term-tag"><em class="xref std std-term">tag</em></a>. References are assumed to have a tag of zero: any
|
|
value in the vector with a non-zero tag is ignored.</p>
|
|
<p>Returns <a class="reference internal" href="error.html#MPS_RES_OK" title="MPS_RES_OK"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_OK</span></tt></a> if the root was registered
|
|
successfully, <a class="reference internal" href="error.html#MPS_RES_MEMORY" title="MPS_RES_MEMORY"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_MEMORY</span></tt></a> if the new root
|
|
description could not be allocated, or another <a class="reference internal" href="../glossary/r.html#term-result-code"><em class="xref std std-term">result code</em></a>
|
|
if there was another error.</p>
|
|
<p>The registered root destription persists until it is destroyed by
|
|
calling <a class="reference internal" href="#mps_root_destroy" title="mps_root_destroy"><tt class="xref c c-func docutils literal"><span class="pre">mps_root_destroy()</span></tt></a>.</p>
|
|
<p>For example:</p>
|
|
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#define TAG_MASK 0x3 </span><span class="cm">/* bottom two bits */</span><span class="cp"></span>
|
|
|
|
<span class="cm">/* Global symbol table. */</span>
|
|
<span class="kt">size_t</span> <span class="n">symtab_size</span><span class="p">;</span>
|
|
<span class="k">struct</span> <span class="p">{</span>
|
|
<span class="n">obj_t</span> <span class="n">symbol</span><span class="p">;</span>
|
|
<span class="n">obj_t</span> <span class="n">value</span><span class="p">;</span>
|
|
<span class="p">}</span> <span class="o">*</span><span class="n">symtab</span><span class="p">;</span>
|
|
|
|
<span class="n">mps_res_t</span> <span class="n">res</span><span class="p">;</span>
|
|
<span class="n">mps_root_t</span> <span class="n">root</span><span class="p">;</span>
|
|
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_root_create_table_masked</span><span class="p">(</span><span class="o">&</span><span class="n">root</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span>
|
|
<span class="n">mps_rank_exact</span><span class="p">(),</span>
|
|
<span class="p">(</span><span class="n">mps_rm_t</span><span class="p">)</span><span class="mi">0</span><span class="p">,</span>
|
|
<span class="n">symtab</span><span class="p">,</span> <span class="n">symtab_size</span> <span class="o">*</span> <span class="mi">2</span><span class="p">,</span>
|
|
<span class="p">(</span><span class="n">mps_word_t</span><span class="p">)</span><span class="n">TAG_MASK</span><span class="p">);</span>
|
|
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">errror</span><span class="p">(</span><span class="s">"can't create symtab root"</span><span class="p">);</span>
|
|
</pre></div>
|
|
</div>
|
|
</dd></dl>
|
|
|
|
<dl class="function">
|
|
<dt id="mps_root_destroy">
|
|
void <tt class="descname">mps_root_destroy</tt><big>(</big><a class="reference internal" href="#mps_root_t" title="mps_root_t">mps_root_t</a><em> root</em><big>)</big><a class="headerlink" href="#mps_root_destroy" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>Deregister a <a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">root</em></a> and destroy its description.</p>
|
|
<p><tt class="docutils literal"><span class="pre">root</span></tt> is the root.</p>
|
|
</dd></dl>
|
|
|
|
</div>
|
|
<div class="section" id="root-introspection">
|
|
<span id="index-8"></span><h2>9.7. Root introspection<a class="headerlink" href="#root-introspection" title="Permalink to this headline">¶</a></h2>
|
|
<dl class="function">
|
|
<dt id="mps_arena_roots_walk">
|
|
void <tt class="descname">mps_arena_roots_walk</tt><big>(</big><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_roots_stepper_t" title="mps_roots_stepper_t">mps_roots_stepper_t</a><em> f</em>, void<em> *p</em>, size_t<em> s</em><big>)</big><a class="headerlink" href="#mps_arena_roots_walk" title="Permalink to this definition">¶</a></dt>
|
|
<dd><div class="admonition-deprecated admonition">
|
|
<p class="first admonition-title">Deprecated</p>
|
|
<p>starting with version 1.111.</p>
|
|
<p class="last">If you think you need this, there’s probably a better way to
|
|
achieve what you’re trying to do. <a class="reference internal" href="../contact.html#contact"><em>Contact us</em></a>.</p>
|
|
</div>
|
|
<p>Visit references in registered <a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">roots</em></a> in 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">arena</span></tt> is the arena whose roots you want to visit.</p>
|
|
<p><tt class="docutils literal"><span class="pre">f</span></tt> is a function that will be called for each reference to an
|
|
object in an <a class="reference internal" href="../glossary/a.html#term-automatic-memory-management"><em class="xref std std-term">automatically</em></a>
|
|
managed <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool class</em></a> that was found in a registered root
|
|
beloging to the arena. It takes four arguments: <tt class="docutils literal"><span class="pre">ref</span></tt> is the
|
|
address of a reference to an object in the arena, <tt class="docutils literal"><span class="pre">root</span></tt> is the
|
|
root in which <tt class="docutils literal"><span class="pre">ref</span></tt> was found, and <tt class="docutils literal"><span class="pre">p</span></tt> and <tt class="docutils literal"><span class="pre">s</span></tt> are the
|
|
corresponding arguments that were passed to
|
|
<a class="reference internal" href="#mps_arena_roots_walk" title="mps_arena_roots_walk"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_roots_walk()</span></tt></a>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">p</span></tt> and <tt class="docutils literal"><span class="pre">s</span></tt> are arguments that will be passed to <tt class="docutils literal"><span class="pre">f</span></tt> each time it
|
|
is called. This is intended to make it easy to pass, for example,
|
|
an array and its size as parameters.</p>
|
|
<p>This function may only be called when the arena is in the
|
|
<a class="reference internal" href="../glossary/p.html#term-parked-state"><em class="xref std std-term">parked state</em></a>.</p>
|
|
<div class="admonition-see-also admonition seealso">
|
|
<p class="first admonition-title">See also</p>
|
|
<p class="last"><a class="reference internal" href="arena.html#topic-arena"><em>Arenas</em></a>.</p>
|
|
</div>
|
|
<div class="admonition-note admonition">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">If a root is <a class="reference internal" href="../glossary/a.html#term-ambiguous-root"><em class="xref std std-term">ambiguous</em></a> then the
|
|
reference might not be to the start of an object; the
|
|
<a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> should handle this case. There is no
|
|
guarantee that the reference corresponds to the actual
|
|
location that holds the pointer to the object (since this
|
|
might be a register, for example), but the actual location
|
|
will be passed if possible. This may aid analysis of roots via
|
|
a debugger.</p>
|
|
</div>
|
|
</dd></dl>
|
|
|
|
<dl class="type">
|
|
<dt id="mps_roots_stepper_t">
|
|
void <tt class="descname">(*mps_roots_stepper_t)</tt><big>(</big><a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em> *ref</em>, <a class="reference internal" href="#mps_root_t" title="mps_root_t">mps_root_t</a><em> root</em>, void<em> *p</em>, size_t<em> s</em><big>)</big><a class="headerlink" href="#mps_roots_stepper_t" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>The type of a <a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">root</em></a> <a class="reference internal" href="../glossary/s.html#term-stepper-function"><em class="xref std std-term">stepper function</em></a>.</p>
|
|
<p>A function of this type can be passed to
|
|
<a class="reference internal" href="#mps_arena_roots_walk" title="mps_arena_roots_walk"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_roots_walk()</span></tt></a>, in which case it will be called
|
|
for each reference into the <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> from a root registered
|
|
with the arena. It receives four arguments:</p>
|
|
<p><tt class="docutils literal"><span class="pre">ref</span></tt> points to a reference in a root. The reference points to
|
|
something in the arena. If the root is <a class="reference internal" href="../glossary/e.html#term-exact-reference"><em class="xref std std-term">exact</em></a> then the reference points to the start of an allocated
|
|
block, but if the root is <a class="reference internal" href="../glossary/a.html#term-ambiguous-reference"><em class="xref std std-term">ambiguous</em></a>
|
|
it might point to somewhere in the middle of an allocated block.</p>
|
|
<p><tt class="docutils literal"><span class="pre">root</span></tt> is the description of the root which contains <tt class="docutils literal"><span class="pre">ref</span></tt>.</p>
|
|
<p><tt class="docutils literal"><span class="pre">p</span></tt> and <tt class="docutils literal"><span class="pre">s</span></tt> are the corresponding values that were passed to
|
|
<a class="reference internal" href="#mps_arena_roots_walk" title="mps_arena_roots_walk"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_roots_walk()</span></tt></a>.</p>
|
|
</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="#">9. Roots</a><ul>
|
|
<li><a class="reference internal" href="#registering-roots">9.1. Registering roots</a></li>
|
|
<li><a class="reference internal" href="#cautions">9.2. Cautions</a></li>
|
|
<li><a class="reference internal" href="#thread-roots">9.3. Thread roots</a></li>
|
|
<li><a class="reference internal" href="#ranks">9.4. Ranks</a></li>
|
|
<li><a class="reference internal" href="#root-modes">9.5. Root modes</a></li>
|
|
<li><a class="reference internal" href="#root-interface">9.6. Root interface</a></li>
|
|
<li><a class="reference internal" href="#root-introspection">9.7. Root introspection</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h4>Previous topic</h4>
|
|
<p class="topless"><a href="thread.html"
|
|
title="previous chapter">8. Threads</a></p>
|
|
<h4>Next topic</h4>
|
|
<p class="topless"><a href="collection.html"
|
|
title="next chapter">10. Garbage collection</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="collection.html" title="10. Garbage collection"
|
|
>next</a> |</li>
|
|
<li class="right" >
|
|
<a href="thread.html" title="8. Threads"
|
|
>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> |