mirror of
git://git.sv.gnu.org/emacs.git
synced 2025-12-26 15:21:51 -08:00
28419106ca
Check in HTML version of the manual (writable on client) so that it will display automatically on the Ravenbrook server and so that we can easily include it in product releases. Copied from Perforce Change: 180338 ServerID: perforce.ravenbrook.com
197 lines
No EOL
14 KiB
HTML
197 lines
No EOL
14 KiB
HTML
|
|
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
|
|
<title>17. Debugging pools — 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="18. Telemetry" href="telemetry.html" />
|
|
<link rel="prev" title="16. 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="18. Telemetry"
|
|
accesskey="N">next</a> |</li>
|
|
<li class="right" >
|
|
<a href="frame.html" title="16. Allocation frames"
|
|
accesskey="P">previous</a> |</li>
|
|
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> »</li>
|
|
<li><a href="index.html" accesskey="U">Reference</a> »</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="document">
|
|
<div class="documentwrapper">
|
|
<div class="bodywrapper">
|
|
<div class="body">
|
|
|
|
<div class="section" id="debugging-pools">
|
|
<span id="topic-debugging"></span><span id="index-0"></span><h1>17. 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 that 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. These patterns can be checked, for
|
|
example 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>.</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 can also be checked, for example just
|
|
before allocation, or when a block of memory is released from the
|
|
pool to the arena, to see that it is unchanged.</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">"postpost"</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">"freefree"</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">res</span> <span class="o">=</span> <span class="n">mps_pool_create</span><span class="p">(</span><span class="o">&</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="o">&</span><span class="n">debug_options</span><span class="p">,</span> <span class="o">&</span><span class="n">fmt</span><span class="p">,</span> <span class="o">&</span><span class="n">chain</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">"can't create debug pool"</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 used to pass options to
|
|
<a class="reference internal" href="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> for debugging <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool classes</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’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> 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> mps_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">16. Allocation frames</a></p>
|
|
<h4>Next topic</h4>
|
|
<p class="topless"><a href="telemetry.html"
|
|
title="next chapter">18. Telemetry</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="18. Telemetry"
|
|
>next</a> |</li>
|
|
<li class="right" >
|
|
<a href="frame.html" title="16. Allocation frames"
|
|
>previous</a> |</li>
|
|
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> »</li>
|
|
<li><a href="index.html" >Reference</a> »</li>
|
|
</ul>
|
|
</div>
|
|
<div class="footer">
|
|
© <a href="../copyright.html">Copyright</a> 2012, Ravenbrook Limited.
|
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
|
|
</div>
|
|
</body>
|
|
</html> |