mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-01-12 06:21:02 -08:00
Code Issues Projects Releases Wiki Activity
emacs/mps/manual/html/pool/amc.html
Gareth Rees 06057a4d52 Bring html up to date. 
Copied from Perforce
 Change: 181168
 ServerID: perforce.ravenbrook.com
2013-03-18 15:13:54 +00:00

256 lines
No EOL
19 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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>4. AMC (Automatic Mostly-Copying) &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="Pool reference" href="index.html" />
<link rel="next" title="5. AMCZ (Automatic Mostly-Copying Zero-rank)" href="amcz.html" />
<link rel="prev" title="1. Choosing a pool class" href="intro.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="amcz.html" title="5. AMCZ (Automatic Mostly-Copying Zero-rank)"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="intro.html" title="1. Choosing a pool class"
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">Pool reference</a> &raquo;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="amc-automatic-mostly-copying">
<span id="pool-amc"></span><span id="index-0"></span><h1>4. AMC (Automatic Mostly-Copying)<a class="headerlink" href="#amc-automatic-mostly-copying" title="Permalink to this headline"></a></h1>
<p><strong>AMC</strong> is a general-purpose <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-class"><em class="xref std std-term">pool class</em></a>. This is the most mature pool
class in the MPS, intended for the majority of objects in the client
program. Use this pool class unless you need a particular feature that
it doesn&#8217;t provide.</p>
<p>&#8220;Mostly Copying&#8221; means that it uses <a class="reference internal" href="../glossary/c.html#term-copying-garbage-collection"><em class="xref std std-term">copying garbage collection</em></a>
except for blocks that are <a class="reference internal" href="../glossary/p.html#term-pinning"><em class="xref std std-term">pinned</em></a> by
<a class="reference internal" href="../glossary/a.html#term-ambiguous-reference"><em class="xref std std-term">ambiguous references</em></a>.</p>
<p>It uses <a class="reference internal" href="../glossary/g.html#term-generational-garbage-collection"><em class="xref std std-term">generational garbage collection</em></a>. That is, it exploits
assumptions about object lifetimes and inter-connection variously
referred to as &#8220;the generational hypothesis&#8221;. In particular, the
following tendencies will be efficiently exploited by an AMC pool:</p>
<ul class="simple">
<li>most objects die young;</li>
<li>objects that don&#8217;t die young will live a long time.</li>
</ul>
<p>In the pool&#8217;s <a class="reference internal" href="../glossary/g.html#term-generation-chain"><em class="xref std std-term">generation chain</em></a>, specify the capacity and
mortality of generations 0 to <em>n</em>−1. Survivors from generation <em>n</em>−1
get promoted into an arena-wide &#8220;top&#8221; generation.</p>
<div class="section" id="amc-properties">
<span id="index-1"></span><h2>4.1. AMC properties<a class="headerlink" href="#amc-properties" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li>Does not support allocation via <a class="reference internal" href="../topic/allocation.html#mps_alloc" title="mps_alloc"><tt class="xref c c-func docutils literal"><span class="pre">mps_alloc()</span></tt></a> or deallocation
via <a class="reference internal" href="../topic/allocation.html#mps_free" title="mps_free"><tt class="xref c c-func docutils literal"><span class="pre">mps_free()</span></tt></a>.</li>
<li>Supports allocation via <a class="reference internal" href="../glossary/a.html#term-allocation-point"><em class="xref std std-term">allocation points</em></a>. If an allocation
point is created in an AMC pool, the call to <a class="reference internal" href="../topic/allocation.html#mps_ap_create" title="mps_ap_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_create()</span></tt></a>
takes no additional parameters.</li>
<li>Supports <a class="reference internal" href="../glossary/a.html#term-allocation-frame"><em class="xref std std-term">allocation frames</em></a> but does not use them to improve
the efficiency of stack-like allocation.</li>
<li>Does not support <a class="reference internal" href="../glossary/s.html#term-segregated-allocation-cache"><em class="xref std std-term">segregated allocation caches</em></a>.</li>
<li>Garbage collections are scheduled automatically. See
<a class="reference internal" href="../topic/collection.html#topic-collection-schedule"><em>Scheduling of collections</em></a>.</li>
<li>Blocks may contain <a class="reference internal" href="../glossary/e.html#term-exact-reference"><em class="xref std std-term">exact references</em></a> to blocks in the same or
other pools (but may not contain <a class="reference internal" href="../glossary/a.html#term-ambiguous-reference"><em class="xref std std-term">ambiguous references</em></a> or
<a class="reference internal" href="../glossary/w.html#term-weak-reference-1"><em class="xref std std-term">weak references<sup>(1)</sup></em></a>, and may not use <a class="reference internal" href="../glossary/r.html#term-remote-reference"><em class="xref std std-term">remote
references</em></a>).</li>
<li>Allocations may be variable in size.</li>
<li>The <a class="reference internal" href="../glossary/a.html#term-alignment"><em class="xref std std-term">alignment</em></a> of blocks is configurable.</li>
<li>Blocks do not have <a class="reference internal" href="../glossary/d.html#term-dependent-object"><em class="xref std std-term">dependent objects</em></a>.</li>
<li>Blocks that are not <a class="reference internal" href="../glossary/r.html#term-reachable"><em class="xref std std-term">reachable</em></a> from a <a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">root</em></a> are
automatically <a class="reference internal" href="../glossary/r.html#term-reclaim"><em class="xref std std-term">reclaimed</em></a>.</li>
<li>Blocks are <a class="reference internal" href="../glossary/s.html#term-scan"><em class="xref std std-term">scanned</em></a>.</li>
<li>Blocks may only be referenced by <a class="reference internal" href="../glossary/b.html#term-base-pointer"><em class="xref std std-term">base pointers</em></a> (unless they
belong to an object format of variant auto-header).</li>
<li>Blocks may be protected by <a class="reference internal" href="../glossary/b.html#term-barrier-1"><em class="xref std std-term">barriers<sup>(1)</sup></em></a>.</li>
<li>Blocks may <a class="reference internal" href="../glossary/m.html#term-moving-garbage-collector"><em class="xref std std-term">move</em></a>.</li>
<li>Blocks may be registered for <a class="reference internal" href="../glossary/f.html#term-finalization"><em class="xref std std-term">finalization</em></a>.</li>
<li>Blocks must belong to an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>.</li>
</ul>
</div>
<div class="section" id="amc-interface">
<span id="index-2"></span><h2>4.2. AMC interface<a class="headerlink" href="#amc-interface" title="Permalink to this headline"></a></h2>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include &quot;mpscamc.h&quot;</span>
</pre></div>
</div>
<dl class="function">
<dt id="mps_class_amc">
<a class="reference internal" href="../topic/pool.html#mps_class_t" title="mps_class_t">mps_class_t</a> <tt class="descname">mps_class_amc</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_class_amc" title="Permalink to this definition"></a></dt>
<dd><p>Return the <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool class</em></a> for an AMC (Automatic
Mostly-Copying) <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a>.</p>
<p>When creating an AMC pool, <a class="reference internal" href="../topic/pool.html#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a> takes two
extra arguments:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="n">mps_pool_t</span> <span class="o">*</span><span class="n">pool_o</span><span class="p">,</span> <span class="n">mps_arena_t</span> <span class="n">arena</span><span class="p">,</span>
<span class="n">mps_class_t</span> <span class="n">mps_class_amc</span><span class="p">(),</span>
<span class="n">mps_fmt_t</span> <span class="n">fmt</span><span class="p">,</span>
<span class="n">mps_chain_t</span> <span class="n">chain</span><span class="p">)</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">fmt</span></tt> specifies the <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> for the objects
allocated in the pool. The format must provide a <a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan
method</em></a>, a <a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip method</em></a>, a <a class="reference internal" href="../glossary/f.html#term-forward-method"><em class="xref std std-term">forward method</em></a>, an
<a class="reference internal" href="../glossary/i.html#term-is-forwarded-method"><em class="xref std std-term">is-forwarded method</em></a> and a <a class="reference internal" href="../glossary/p.html#term-padding-method"><em class="xref std std-term">padding method</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">chain</span></tt> specifies the <a class="reference internal" href="../glossary/g.html#term-generation-chain"><em class="xref std std-term">generation chain</em></a> for the pool.</p>
</dd></dl>
</div>
<div class="section" id="amc-introspection">
<span id="index-3"></span><h2>4.3. AMC introspection<a class="headerlink" href="#amc-introspection" title="Permalink to this headline"></a></h2>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include &quot;mpscamc.h&quot;</span>
</pre></div>
</div>
<dl class="function">
<dt id="mps_amc_apply">
void <tt class="descname">mps_amc_apply</tt><big>(</big><a class="reference internal" href="../topic/pool.html#mps_pool_t" title="mps_pool_t">mps_pool_t</a><em>&nbsp;pool</em>, <a class="reference internal" href="#mps_amc_apply_stepper_t" title="mps_amc_apply_stepper_t">mps_amc_apply_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_amc_apply" title="Permalink to this definition"></a></dt>
<dd><p>Visit all <a class="reference internal" href="../glossary/f.html#term-formatted-object"><em class="xref std std-term">formatted objects</em></a> in an AMC pool.</p>
<p><tt class="docutils literal"><span class="pre">pool</span></tt> is the pool whose formatted objects 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 formatted object in
the pool.</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>It is an error to call this function when the <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> is not
in the <a class="reference internal" href="../glossary/p.html#term-parked-state"><em class="xref std std-term">parked state</em></a>. You need to call
<a class="reference internal" href="../topic/arena.html#mps_arena_collect" title="mps_arena_collect"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_collect()</span></tt></a> or <a class="reference internal" href="../topic/arena.html#mps_arena_park" title="mps_arena_park"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_park()</span></tt></a> before
calling <a class="reference internal" href="#mps_amc_apply" title="mps_amc_apply"><tt class="xref c c-func docutils literal"><span class="pre">mps_amc_apply()</span></tt></a>.</p>
<p>The function <tt class="docutils literal"><span class="pre">f</span></tt> will be called on both <a class="reference internal" href="../glossary/c.html#term-client-object"><em class="xref std std-term">client</em></a> and <a class="reference internal" href="../glossary/p.html#term-padding-object"><em class="xref std std-term">padding objects</em></a>. It is the job of <tt class="docutils literal"><span class="pre">f</span></tt> to
distinguish, if necessary, between the two. It may also be called
on <a class="reference internal" href="../glossary/d.html#term-dead"><em class="xref std std-term">dead</em></a> objects that the collector has not recycled or has
been unable to recycle.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">There is no equivalent function for other pool classes, but
there is a more general function
<a class="reference internal" href="../topic/format.html#mps_arena_formatted_objects_walk" title="mps_arena_formatted_objects_walk"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_formatted_objects_walk()</span></tt></a> that visits all
formatted objects in the arena.</p>
</div>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">This function is intended for heap analysis, tuning, and
debugging, not for frequent use in production.</p>
</div>
</dd></dl>
<dl class="type">
<dt id="mps_amc_apply_stepper_t">
void <tt class="descname">(*mps_amc_apply_stepper_t)</tt><big>(</big><a class="reference internal" href="../topic/interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;addr</em>, void<em>&nbsp;*p</em>, size_t<em>&nbsp;s</em><big>)</big><a class="headerlink" href="#mps_amc_apply_stepper_t" title="Permalink to this definition"></a></dt>
<dd><p>The type of a <a class="reference internal" href="../glossary/s.html#term-stepper-function"><em class="xref std std-term">stepper function</em></a> for <a class="reference internal" href="../glossary/f.html#term-formatted-object"><em class="xref std std-term">formatted
objects</em></a> in an AMC pool.</p>
<p><tt class="docutils literal"><span class="pre">addr</span></tt> is the address of an object in the pool.</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 arguments that were passed
to <a class="reference internal" href="#mps_amc_apply" title="mps_amc_apply"><tt class="xref c c-func docutils literal"><span class="pre">mps_amc_apply()</span></tt></a>.</p>
<p>The function may not call any function in the MPS. It may access:</p>
<ol class="loweralpha simple">
<li>memory inside the object or block pointed to by <tt class="docutils literal"><span class="pre">addr</span></tt>;</li>
<li>memory managed by the MPS that is in pools that do not protect
their contents;</li>
<li>memory not managed by the MPS;</li>
</ol>
<p>It must not access other memory managed by the MPS.</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="#">4. AMC (Automatic Mostly-Copying)</a><ul>
<li><a class="reference internal" href="#amc-properties">4.1. AMC properties</a></li>
<li><a class="reference internal" href="#amc-interface">4.2. AMC interface</a></li>
<li><a class="reference internal" href="#amc-introspection">4.3. AMC introspection</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="intro.html"
title="previous chapter">1. Choosing a pool class</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="amcz.html"
title="next chapter">5. AMCZ (Automatic Mostly-Copying Zero-rank)</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="amcz.html" title="5. AMCZ (Automatic Mostly-Copying Zero-rank)"
>next</a> |</li>
<li class="right" >
<a href="intro.html" title="1. Choosing a pool class"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Pool 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