mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-26 07:11:34 -08:00
Code Issues Projects Releases Wiki Activity
emacs/mps/manual/html/topic/pattern.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

241 lines
No EOL
17 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>16. Allocation patterns &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="17. Allocation frames" href="frame.html" />
<link rel="prev" title="15. Segregated allocation caches" href="cache.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="frame.html" title="17. Allocation frames"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="cache.html" title="15. Segregated allocation caches"
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="allocation-patterns">
<span id="topic-pattern"></span><span id="index-0"></span><h1>16. Allocation patterns<a class="headerlink" href="#allocation-patterns" title="Permalink to this headline"></a></h1>
<p>An <em class="dfn">allocation pattern</em> is a hint to the MPS to expect a
particular pattern of allocation on an <a class="reference internal" href="../glossary/a.html#term-allocation-point"><em class="xref std std-term">allocation point</em></a>. The
MPS may use this hint to schedule more effective garbage collection.</p>
<p>There are two allocation patterns, <a class="reference internal" href="#mps_alloc_pattern_ramp" title="mps_alloc_pattern_ramp"><tt class="xref c c-func docutils literal"><span class="pre">mps_alloc_pattern_ramp()</span></tt></a>
and <a class="reference internal" href="#mps_alloc_pattern_ramp_collect_all" title="mps_alloc_pattern_ramp_collect_all"><tt class="xref c c-func docutils literal"><span class="pre">mps_alloc_pattern_ramp_collect_all()</span></tt></a>.</p>
<dl class="type">
<dt id="mps_alloc_pattern_t">
<tt class="descname">mps_alloc_pattern_t</tt><a class="headerlink" href="#mps_alloc_pattern_t" title="Permalink to this definition"></a></dt>
<dd><p>The type of <a class="reference internal" href="../glossary/a.html#term-allocation-pattern"><em class="xref std std-term">allocation patterns</em></a>.</p>
</dd></dl>
<dl class="function">
<dt id="mps_ap_alloc_pattern_begin">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_ap_alloc_pattern_begin</tt><big>(</big><a class="reference internal" href="allocation.html#mps_ap_t" title="mps_ap_t">mps_ap_t</a><em>&nbsp;ap</em>, <a class="reference internal" href="#mps_alloc_pattern_t" title="mps_alloc_pattern_t">mps_alloc_pattern_t</a><em>&nbsp;alloc_pattern</em><big>)</big><a class="headerlink" href="#mps_ap_alloc_pattern_begin" title="Permalink to this definition"></a></dt>
<dd><p>Start a period of allocation that behaves according to an
<a class="reference internal" href="../glossary/a.html#term-allocation-pattern"><em class="xref std std-term">allocation pattern</em></a>. The period persists until a
corresponding call to <a class="reference internal" href="#mps_ap_alloc_pattern_end" title="mps_ap_alloc_pattern_end"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_alloc_pattern_end()</span></tt></a>.</p>
<p><tt class="docutils literal"><span class="pre">ap</span></tt> is the <a class="reference internal" href="../glossary/a.html#term-allocation-point"><em class="xref std std-term">allocation point</em></a> in which the patterned
allocation will occur.</p>
<p><tt class="docutils literal"><span class="pre">alloc_pattern</span></tt> is the allocation pattern.</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 allocation pattern is
supported by this allocation point. At present this is always the
case, but in future this function may return another <a class="reference internal" href="../glossary/r.html#term-result-code"><em class="xref std std-term">result
code</em></a> if the allocation pattern is not supported by the allocation
point.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">It is harmless to call <a class="reference internal" href="#mps_ap_alloc_pattern_begin" title="mps_ap_alloc_pattern_begin"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_alloc_pattern_begin()</span></tt></a>
even if it isn&#8217;t supported by the allocation point. The
pattern is simply ignored in that case.</p>
</div>
<p>If <a class="reference internal" href="#mps_ap_alloc_pattern_begin" title="mps_ap_alloc_pattern_begin"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_alloc_pattern_begin()</span></tt></a> is used multiple times on
the same allocation point without intervening calls to
<a class="reference internal" href="#mps_ap_alloc_pattern_end" title="mps_ap_alloc_pattern_end"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_alloc_pattern_end()</span></tt></a>, the calls match in a
stack-like way, outermost and innermost: that is, allocation
patterns may nest, but not otherwise overlap.</p>
<p>Some allocation patterns may additionally support overlap: if so,
the documentation for the individual pattern types will specify
this.</p>
</dd></dl>
<dl class="function">
<dt id="mps_ap_alloc_pattern_end">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_ap_alloc_pattern_end</tt><big>(</big><a class="reference internal" href="allocation.html#mps_ap_t" title="mps_ap_t">mps_ap_t</a><em>&nbsp;ap</em>, <a class="reference internal" href="#mps_alloc_pattern_t" title="mps_alloc_pattern_t">mps_alloc_pattern_t</a><em>&nbsp;alloc_pattern</em><big>)</big><a class="headerlink" href="#mps_ap_alloc_pattern_end" title="Permalink to this definition"></a></dt>
<dd><p>End a period of allocation on an <a class="reference internal" href="../glossary/a.html#term-allocation-point"><em class="xref std std-term">allocation point</em></a> that
behaves according to an <a class="reference internal" href="../glossary/a.html#term-allocation-pattern"><em class="xref std std-term">allocation pattern</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">ap</span></tt> is the allocation point in which the patterned allocation
occurred.</p>
<p><tt class="docutils literal"><span class="pre">alloc_pattern</span></tt> is the allocation pattern.</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 period of allocation was
successfully ended, or <a class="reference internal" href="error.html#MPS_RES_FAIL" title="MPS_RES_FAIL"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_FAIL</span></tt></a> if there was no
matching call to <a class="reference internal" href="#mps_ap_alloc_pattern_begin" title="mps_ap_alloc_pattern_begin"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_alloc_pattern_begin()</span></tt></a>. Calls match
in a stack-like way, outermost and innermost: that is, allocation
patterns may nest, but not otherwise overlap.</p>
<p>Some allocation patterns may additionally support overlap: if so,
the documentation for the individual pattern types will specify
this.</p>
</dd></dl>
<dl class="function">
<dt id="mps_ap_alloc_pattern_reset">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_ap_alloc_pattern_reset</tt><big>(</big><a class="reference internal" href="allocation.html#mps_ap_t" title="mps_ap_t">mps_ap_t</a><em>&nbsp;ap</em><big>)</big><a class="headerlink" href="#mps_ap_alloc_pattern_reset" title="Permalink to this definition"></a></dt>
<dd><p>End all <a class="reference internal" href="../glossary/a.html#term-allocation-pattern"><em class="xref std std-term">patterned allocation</em></a> on an
<a class="reference internal" href="../glossary/a.html#term-allocation-point"><em class="xref std std-term">allocation point</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">ap</span></tt> is the allocation point on which to end all patterned
allocation.</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>. It may fail in future if certain
allocation patterns cannot be ended for that allocation point at
that point in time.</p>
<p>This function may be used to recover from error conditions.</p>
</dd></dl>
<div class="section" id="ramp-allocation">
<span id="topic-pattern-ramp"></span><span id="index-1"></span><h2>16.1. Ramp allocation<a class="headerlink" href="#ramp-allocation" title="Permalink to this headline"></a></h2>
<p><em class="dfn">Ramp allocation</em> a pattern of allocation whereby the
<a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> builds up an increasingly large data structure,
the live size of which increases until a particular time, at which
time most of the data structure is discarded, resulting in sharp
cutoff and decline in the live size.</p>
<p>This pattern is useful if you are building a structure that involves
temporarily allocating much more memory than will fit into your
<a class="reference internal" href="../glossary/n.html#term-nursery-generation"><em class="xref std std-term">nursery generation</em></a>. The ramp allocation pattern causes the
collection of the nursery generation to be deferred until the ramp
allocation is over.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">Ramp allocation is only supported by <a class="reference internal" href="../pool/amc.html#pool-amc"><em>AMC (Automatic Mostly-Copying)</em></a>.</p>
</div>
<dl class="function">
<dt id="mps_alloc_pattern_ramp">
<a class="reference internal" href="#mps_alloc_pattern_t" title="mps_alloc_pattern_t">mps_alloc_pattern_t</a> <tt class="descname">mps_alloc_pattern_ramp</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_alloc_pattern_ramp" title="Permalink to this definition"></a></dt>
<dd><p>Return an <a class="reference internal" href="../glossary/a.html#term-allocation-pattern"><em class="xref std std-term">allocation pattern</em></a> indicating that allocation
will follow a <a class="reference internal" href="../glossary/r.html#term-ramp-allocation"><em class="xref std std-term">ramp allocation</em></a> pattern.</p>
<p>This indicates to the MPS that most of the blocks allocated after
the call to <a class="reference internal" href="#mps_ap_alloc_pattern_begin" title="mps_ap_alloc_pattern_begin"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_alloc_pattern_begin()</span></tt></a> are likely to be
<a class="reference internal" href="../glossary/d.html#term-dead"><em class="xref std std-term">dead</em></a> by the time of the corresponding call to
<a class="reference internal" href="#mps_ap_alloc_pattern_end" title="mps_ap_alloc_pattern_end"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_alloc_pattern_end()</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="mps_alloc_pattern_ramp_collect_all">
<a class="reference internal" href="#mps_alloc_pattern_t" title="mps_alloc_pattern_t">mps_alloc_pattern_t</a> <tt class="descname">mps_alloc_pattern_ramp_collect_all</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_alloc_pattern_ramp_collect_all" title="Permalink to this definition"></a></dt>
<dd><p>Return an <a class="reference internal" href="../glossary/a.html#term-allocation-pattern"><em class="xref std std-term">allocation pattern</em></a> indicating that allocation
will follow a <a class="reference internal" href="../glossary/r.html#term-ramp-allocation"><em class="xref std std-term">ramp allocation</em></a> pattern, and that the next
<a class="reference internal" href="../glossary/g.html#term-garbage-collection"><em class="xref std std-term">garbage collection</em></a> following the ramp should be a full
collection.</p>
<p>This indicates to the MPS that most of the blocks allocated after
the call to <a class="reference internal" href="#mps_ap_alloc_pattern_begin" title="mps_ap_alloc_pattern_begin"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_alloc_pattern_begin()</span></tt></a> are likely to be
<a class="reference internal" href="../glossary/d.html#term-dead"><em class="xref std std-term">dead</em></a> by the time of the corresponding call to
<a class="reference internal" href="#mps_ap_alloc_pattern_end" title="mps_ap_alloc_pattern_end"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_alloc_pattern_end()</span></tt></a>.</p>
<p>This allocation pattern may nest with, but should not otherwise
overlap with, allocation patterns of type
<a class="reference internal" href="#mps_alloc_pattern_ramp" title="mps_alloc_pattern_ramp"><tt class="xref c c-func docutils literal"><span class="pre">mps_alloc_pattern_ramp()</span></tt></a>. In this case, the MPS may defer
the full collection until after all ramp allocation patterns have
ended.</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="#">16. Allocation patterns</a><ul>
<li><a class="reference internal" href="#ramp-allocation">16.1. Ramp allocation</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="cache.html"
title="previous chapter">15. Segregated allocation caches</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="frame.html"
title="next chapter">17. Allocation frames</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="frame.html" title="17. Allocation frames"
>next</a> |</li>
<li class="right" >
<a href="cache.html" title="15. Segregated allocation caches"
>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