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/debugging.html
Gareth Rees 2ed2ff1893 Updated manual html 
Copied from Perforce
 Change: 181750
 ServerID: perforce.ravenbrook.com
2013-05-13 21:04:49 +01:00

242 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>18. Debugging pools &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="19. Telemetry" href="telemetry.html" />
<link rel="prev" title="17. Allocation frames" href="frame.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="telemetry.html" title="19. Telemetry"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="frame.html" title="17. Allocation frames"
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="debugging-pools">
<span id="topic-debugging"></span><span id="index-0"></span><h1>18. Debugging pools<a class="headerlink" href="#debugging-pools" title="Permalink to this headline"></a></h1>
<p>Several <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool classes</em></a> have debugging counterparts:</p>
<table border="1" class="docutils">
<colgroup>
<col width="36%" />
<col width="64%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Pool class</th>
<th class="head">Debugging counterpart</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><a class="reference internal" href="../pool/ams.html#pool-ams"><em>AMS (Automatic Mark and Sweep)</em></a></td>
<td><a class="reference internal" href="../pool/ams.html#mps_class_ams_debug" title="mps_class_ams_debug"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_ams_debug()</span></tt></a></td>
</tr>
<tr class="row-odd"><td><a class="reference internal" href="../pool/mv.html#pool-mv"><em>MV (Manual Variable)</em></a></td>
<td><a class="reference internal" href="../pool/mv.html#mps_class_mv_debug" title="mps_class_mv_debug"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mv_debug()</span></tt></a></td>
</tr>
<tr class="row-even"><td><a class="reference internal" href="../pool/mvff.html#pool-mvff"><em>MVFF (Manual Variable First Fit)</em></a></td>
<td><a class="reference internal" href="../pool/mvff.html#mps_class_mvff_debug" title="mps_class_mvff_debug"><tt class="xref c c-func docutils literal"><span class="pre">mps_class_mvff_debug()</span></tt></a></td>
</tr>
</tbody>
</table>
<p>These debugging pool classes provide two features that are useful for
debugging:</p>
<ul>
<li><p id="index-1"><em class="dfn">fenceposts</em> are patterns of data that are written before and
after each allocated block. In <a class="reference internal" href="../glossary/m.html#term-manual-memory-management"><em class="xref std std-term">manually managed</em></a> pools, fenceposts are checked when the block is
deallocated, to see that they are unchanged. This helps detect
underwriting and <a class="reference internal" href="../glossary/o.html#term-overwriting-error"><em class="xref std std-term">overwriting errors</em></a>. Fenceposts for all
objects in a pool are checked when the pool is destroyed, and can be
checked at any time by calling <a class="reference internal" href="#mps_pool_check_fenceposts" title="mps_pool_check_fenceposts"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_check_fenceposts()</span></tt></a>.</p>
</li>
<li><p id="index-2"><em class="dfn">free space splatting</em> overwrites recycled space with a pattern
of data. If the pattern is designed so that it does not resemble a
live object (and if code checks the consistency of its data
structues), then this helps to detect <a class="reference internal" href="../glossary/d.html#term-dangling-pointer"><em class="xref std std-term">dangling pointer</em></a>
dereferences. The pattern is checked just before allocation, and
when a block of memory is released from the pool to the arena, to
see that it is unchanged. All free space in a pool can be checked
for the pattern at any time by calling
<a class="reference internal" href="#mps_pool_check_free_space" title="mps_pool_check_free_space"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_check_free_space()</span></tt></a>.</p>
</li>
</ul>
<p>The <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> specifies templates for both of these
features via the <a class="reference internal" href="#mps_pool_debug_option_s" title="mps_pool_debug_option_s"><tt class="xref c c-type docutils literal"><span class="pre">mps_pool_debug_option_s</span></tt></a> structure. This
allows it to specify patterns:</p>
<ul class="simple">
<li>that mimic illegal data values;</li>
<li>that cause bus errors if wrongly interpreted as pointers;</li>
<li>that cause assertions to fire if wrongly interpreted as data values;</li>
<li>that contain an instruction sequence that wold cause the program to
signal an error or stop if wrongly interpreted as executable code.</li>
</ul>
<p>For example:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_pool_debug_option_s</span> <span class="n">debug_options</span> <span class="o">=</span> <span class="p">{</span>
<span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="p">)</span><span class="s">&quot;postpost&quot;</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span>
<span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="p">)</span><span class="s">&quot;freefree&quot;</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span>
<span class="p">};</span>
<span class="n">mps_pool_t</span> <span class="n">pool</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_ARGS_BEGIN</span><span class="p">(</span><span class="n">args</span><span class="p">)</span> <span class="p">{</span>
<span class="n">MPS_ARGS_ADD</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">MPS_KEY_POOL_DEBUG_OPTIONS</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">debug_options</span><span class="p">);</span>
<span class="n">MPS_ARGS_ADD</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">MPS_KEY_FORMAT</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">fmt</span><span class="p">);</span>
<span class="n">MPS_ARGS_ADD</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">MPS_KEY_CHAIN</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">chain</span><span class="p">);</span>
<span class="n">MPS_ARGS_DONE</span><span class="p">(</span><span class="n">args</span><span class="p">);</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_pool_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">pool</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">mps_class_ams_debug</span><span class="p">(),</span> <span class="n">args</span><span class="p">);</span>
<span class="p">}</span> <span class="n">MPS_ARGS_END</span><span class="p">(</span><span class="n">args</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;can&#39;t create debug pool&quot;</span><span class="p">);</span>
</pre></div>
</div>
<dl class="type">
<dt id="mps_pool_debug_option_s">
<tt class="descname">mps_pool_debug_option_s</tt><a class="headerlink" href="#mps_pool_debug_option_s" title="Permalink to this definition"></a></dt>
<dd><p>The type of the structure passed as the
<tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_POOL_DEBUG_OPTIONS</span></tt> keyword argument to
<a class="reference internal" href="pool.html#mps_pool_create_k" title="mps_pool_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create_k()</span></tt></a> when creating a debugging <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool
class</em></a>.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">mps_pool_debug_option_s</span> <span class="p">{</span>
<span class="kt">void</span> <span class="o">*</span><span class="n">fence_template</span><span class="p">;</span>
<span class="kt">size_t</span> <span class="n">fence_size</span><span class="p">;</span>
<span class="kt">void</span> <span class="o">*</span><span class="n">free_template</span><span class="p">;</span>
<span class="kt">size_t</span> <span class="n">free_size</span><span class="p">;</span>
<span class="p">}</span> <span class="n">mps_pool_debug_option_s</span><span class="p">;</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">fence_template</span></tt> points to a template for <a class="reference internal" href="../glossary/f.html#term-fencepost"><em class="xref std std-term">fenceposts</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">fence_size</span></tt> is the <a class="reference internal" href="../glossary/s.html#term-size"><em class="xref std std-term">size</em></a> of <tt class="docutils literal"><span class="pre">fence_template</span></tt> in
<a class="reference internal" href="../glossary/b.html#term-byte-1"><em class="xref std std-term">bytes<sup>(1)</sup></em></a>, or zero if the debugging pool should not use
fenceposts.</p>
<p><tt class="docutils literal"><span class="pre">free_template</span></tt> points to a template for splatting free space.</p>
<p><tt class="docutils literal"><span class="pre">free_size</span></tt> is the <a class="reference internal" href="../glossary/s.html#term-size"><em class="xref std std-term">size</em></a> of <tt class="docutils literal"><span class="pre">free_template</span></tt> in bytes, or
zero if the debugging pool should not splat free space.</p>
<p>Both <tt class="docutils literal"><span class="pre">fence_size</span></tt> and <tt class="docutils literal"><span class="pre">free_size</span></tt> must be a multiple of the
<a class="reference internal" href="../glossary/a.html#term-alignment"><em class="xref std std-term">alignment</em></a> of the <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a>, and also a multiple of the
alignment of the pool&#8217;s <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> if it has one.</p>
<p>The debugging pool will copy the <tt class="docutils literal"><span class="pre">fence_size</span></tt> bytes pointed to by
<tt class="docutils literal"><span class="pre">fence_template</span></tt> in a repeating pattern onto each fencepost during
allocation, and it will copy the bytes pointed to by
<tt class="docutils literal"><span class="pre">free_template</span></tt> in a repeating pattern over free space after the
space is reclaimed.</p>
<p>The MPS may not always use the whole of a template: it may use
pieces smaller than the given size, for example to pad out part of
a block that was left unused because of alignment requirements.</p>
</dd></dl>
<dl class="function">
<dt id="mps_pool_check_fenceposts">
void <tt class="descname">mps_pool_check_fenceposts</tt><big>(</big><a class="reference internal" href="pool.html#mps_pool_t" title="mps_pool_t">mps_pool_t</a><em>&nbsp;pool</em><big>)</big><a class="headerlink" href="#mps_pool_check_fenceposts" title="Permalink to this definition"></a></dt>
<dd><p>Check all the <a class="reference internal" href="../glossary/f.html#term-fencepost"><em class="xref std std-term">fenceposts</em></a> in a <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">pool</span></tt> is the pool whose fenceposts are to be checked.</p>
<p>If a corrupted fencepost is found, the MPS will <a class="reference internal" href="../glossary/a.html#term-assertion"><em class="xref std std-term">assert</em></a>. It is only useful to call this on a <a class="reference internal" href="../glossary/d.html#term-debugging-pool"><em class="xref std std-term">debugging
pool</em></a> that has fenceposts turned on. It does nothing on
non-debugging pools.</p>
</dd></dl>
<dl class="function">
<dt id="mps_pool_check_free_space">
void <tt class="descname">mps_pool_check_free_space</tt><big>(</big><a class="reference internal" href="pool.html#mps_pool_t" title="mps_pool_t">mps_pool_t</a><em>&nbsp;pool</em><big>)</big><a class="headerlink" href="#mps_pool_check_free_space" title="Permalink to this definition"></a></dt>
<dd><p>Check all the free space in a <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a> for <a class="reference internal" href="../glossary/o.html#term-overwriting-error"><em class="xref std std-term">overwriting
errors</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">pool</span></tt> is the pool whose free space is to be checked.</p>
<p>If corrupted free space is found, the MPS will <a class="reference internal" href="../glossary/a.html#term-assertion"><em class="xref std std-term">assert</em></a>. It is only useful to call this on a <a class="reference internal" href="../glossary/d.html#term-debugging-pool"><em class="xref std std-term">debugging
pool</em></a> that has free space splatting turned on. It does nothing on
non-debugging pools.</p>
</dd></dl>
</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>
<h4>Previous topic</h4>
<p class="topless"><a href="frame.html"
title="previous chapter">17. Allocation frames</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="telemetry.html"
title="next chapter">19. Telemetry</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="telemetry.html" title="19. Telemetry"
>next</a> |</li>
<li class="right" >
<a href="frame.html" title="17. Allocation frames"
>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