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

658 lines
No EOL
64 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>10. Roots &mdash; Memory Pool System 1.111.0 documentation</title>
<link rel="stylesheet" href="../_static/mps.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.111.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Memory Pool System 1.111.0 documentation" href="../index.html" />
<link rel="up" title="Reference" href="index.html" />
<link rel="next" title="11. Garbage collection" href="collection.html" />
<link rel="prev" title="9. 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="11. Garbage collection"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="thread.html" title="9. Threads"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" accesskey="U">Reference</a> &raquo;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="roots">
<span id="topic-root"></span><span id="index-0"></span><h1>10. 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&#8217;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>10.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 registered 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&#8217;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&#8217;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&#8217;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&#8217;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&#8217;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>10.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>10.3. Thread roots<a class="headerlink" href="#thread-roots" title="Permalink to this headline"></a></h2>
<p>Every thread&#8217;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&#8217;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. The bottom of the relevant part of stack can be found by
taking the address of a local variable in the function that calls the
main work function of your thread. You should take care to ensure that
the work function is not inlined so that the address is definitely in
the stack frame below any potential roots.</p>
<p id="index-4">For example, here&#8217;s the code from the toy Scheme interpreter that
registers a thread root and then calls 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">int</span> <span class="n">exit_code</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">&amp;</span><span class="n">marker</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">&amp;</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">&quot;Couldn&#39;t register thread&quot;</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">&amp;</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">&quot;Couldn&#39;t create root&quot;</span><span class="p">);</span>
<span class="n">exit_code</span> <span class="o">=</span> <span class="n">start</span><span class="p">(</span><span class="n">argc</span><span class="p">,</span> <span class="n">argv</span><span class="p">);</span>
<span class="n">mps_root_destroy</span><span class="p">(</span><span class="n">reg_root</span><span class="p">);</span>
<span class="n">mps_thread_dereg</span><span class="p">(</span><span class="kr">thread</span><span class="p">);</span>
</pre></div>
</div>
</div>
<div class="section" id="ranks">
<span id="index-5"></span><h2>10.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>10.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&#8217;t work as described, since
you can&#8217;t reliably create 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&#8217;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&#8217;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&#8217;t cope with writing to protected pages.</p>
</div>
</dd></dl>
</div>
<div class="section" id="root-interface">
<span id="index-7"></span><h2>10.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&#8217;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>&nbsp;*root_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="#mps_rank_t" title="mps_rank_t">mps_rank_t</a><em>&nbsp;rank</em>, <a class="reference internal" href="#mps_rm_t" title="mps_rm_t">mps_rm_t</a><em>&nbsp;rm</em>, <a class="reference internal" href="#mps_root_scan_t" title="mps_root_scan_t">mps_root_scan_t</a><em>&nbsp;root_scan</em>, void<em>&nbsp;*p</em>, size_t<em>&nbsp;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 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="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>&nbsp;ss</em>, void<em>&nbsp;*p</em>, size_t<em>&nbsp;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, it is 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>&nbsp;*root_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="#mps_rank_t" title="mps_rank_t">mps_rank_t</a><em>&nbsp;rank</em>, <a class="reference internal" href="#mps_rm_t" title="mps_rm_t">mps_rm_t</a><em>&nbsp;rm</em>, <a class="reference internal" href="format.html#mps_fmt_scan_t" title="mps_fmt_scan_t">mps_fmt_scan_t</a><em>&nbsp;fmt_scan</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;base</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;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 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_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>&nbsp;*root_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="#mps_rank_t" title="mps_rank_t">mps_rank_t</a><em>&nbsp;rank</em>, <a class="reference internal" href="#mps_rm_t" title="mps_rm_t">mps_rm_t</a><em>&nbsp;rm</em>, <a class="reference internal" href="thread.html#mps_thr_t" title="mps_thr_t">mps_thr_t</a><em>&nbsp;thr</em>, <a class="reference internal" href="#mps_reg_scan_t" title="mps_reg_scan_t">mps_reg_scan_t</a><em>&nbsp;reg_scan</em>, void<em>&nbsp;*p</em>, size_t<em>&nbsp;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&#8217;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 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>
<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&#8217;re in a position where you need
this, for example, if you&#8217;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>&nbsp;ss</em>, <a class="reference internal" href="thread.html#mps_thr_t" title="mps_thr_t">mps_thr_t</a><em>&nbsp;thr</em>, void<em>&nbsp;*p</em>, size_t<em>&nbsp;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, it is 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&#8217;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>&nbsp;*root_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="#mps_rank_t" title="mps_rank_t">mps_rank_t</a><em>&nbsp;rank</em>, <a class="reference internal" href="#mps_rm_t" title="mps_rm_t">mps_rm_t</a><em>&nbsp;rm</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;*base</em>, size_t<em>&nbsp;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>&nbsp;*root_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="#mps_rank_t" title="mps_rank_t">mps_rank_t</a><em>&nbsp;rank</em>, <a class="reference internal" href="#mps_rm_t" title="mps_rm_t">mps_rm_t</a><em>&nbsp;rm</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;*base</em>, size_t<em>&nbsp;count</em>, <a class="reference internal" href="interface.html#mps_word_t" title="mps_word_t">mps_word_t</a><em>&nbsp;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 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>
<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">&amp;</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">&quot;can&#39;t create symtab root&quot;</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>&nbsp;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>10.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>&nbsp;arena</em>, <a class="reference internal" href="#mps_roots_stepper_t" title="mps_roots_stepper_t">mps_roots_stepper_t</a><em>&nbsp;f</em>, void<em>&nbsp;*p</em>, size_t<em>&nbsp;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&#8217;s probably a better way to
achieve what you&#8217;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
belonging 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>&nbsp;*ref</em>, <a class="reference internal" href="#mps_root_t" title="mps_root_t">mps_root_t</a><em>&nbsp;root</em>, void<em>&nbsp;*p</em>, size_t<em>&nbsp;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="#">10. Roots</a><ul>
<li><a class="reference internal" href="#registering-roots">10.1. Registering roots</a></li>
<li><a class="reference internal" href="#cautions">10.2. Cautions</a></li>
<li><a class="reference internal" href="#thread-roots">10.3. Thread roots</a></li>
<li><a class="reference internal" href="#ranks">10.4. Ranks</a></li>
<li><a class="reference internal" href="#root-modes">10.5. Root modes</a></li>
<li><a class="reference internal" href="#root-interface">10.6. Root interface</a></li>
<li><a class="reference internal" href="#root-introspection">10.7. Root introspection</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="thread.html"
title="previous chapter">9. Threads</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="collection.html"
title="next chapter">11. Garbage collection</a></p><h4>Downloads</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/release/1.111.0/">MPS Kit release 1.111.0</a><br>
<a href="http://www.ravenbrook.com/project/mps/release/">All MPS Kit releases</a>
</p>
<h4>Issues</h4>
<p class="topless">
<a href="http://www.ravenbrook.com/project/mps/issue/?action=list&amp;view=status%3dopen&amp;display=Job:Priority:Title&amp;sort=Priority">Known issues</a><br>
<a href="http://www.ravenbrook.com/project/mps/issue/?action=fixed&release_fixed=1.111.0">Issues fixed in release 1.111.0</a>
</p><h4>Contact us</h4>
<p class="topless"><a href="mailto:mps-questions@ravenbrook.com">mps-questions@ravenbrook.com</a></p>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="collection.html" title="11. Garbage collection"
>next</a> |</li>
<li class="right" >
<a href="thread.html" title="9. Threads"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Reference</a> &raquo;</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">Copyright</a> 2013, Ravenbrook Limited.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
Reference in a new issue View git blame Copy permalink