mirror of
git://git.sv.gnu.org/emacs.git
synced 2025-12-27 07:41:28 -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
221 lines
No EOL
15 KiB
HTML
221 lines
No EOL
15 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>4. 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="5. Allocation" href="allocation.html" />
|
|
<link rel="prev" title="3. Arenas" href="arena.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="allocation.html" title="5. Allocation"
|
|
accesskey="N">next</a> |</li>
|
|
<li class="right" >
|
|
<a href="arena.html" title="3. Arenas"
|
|
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="pools">
|
|
<span id="topic-pool"></span><span id="index-0"></span><h1>4. Pools<a class="headerlink" href="#pools" title="Permalink to this headline">¶</a></h1>
|
|
<p>Within an <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> a client program creates one or more pools. A
|
|
pool is responsible for requesting memory from the <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> and
|
|
making it available for allocation.</p>
|
|
<dl class="type">
|
|
<dt id="mps_pool_t">
|
|
<tt class="descname">mps_pool_t</tt><a class="headerlink" href="#mps_pool_t" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>The type of <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pools</em></a>.</p>
|
|
<p>A pool is responsible for requesting memory from the <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a>
|
|
and making it available to the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> via
|
|
<a class="reference internal" href="allocation.html#mps_alloc" title="mps_alloc"><tt class="xref c c-func docutils literal"><span class="pre">mps_alloc()</span></tt></a> or via an <a class="reference internal" href="../glossary/a.html#term-allocation-point"><em class="xref std std-term">allocation point</em></a>.</p>
|
|
</dd></dl>
|
|
|
|
<dl class="function">
|
|
<dt id="mps_pool_create">
|
|
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_pool_create</tt><big>(</big><a class="reference internal" href="#mps_pool_t" title="mps_pool_t">mps_pool_t</a><em> *pool_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em> arena</em>, <a class="reference internal" href="#mps_class_t" title="mps_class_t">mps_class_t</a><em> class</em>, ...<big>)</big><a class="headerlink" href="#mps_pool_create" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>Create a <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</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">pool_o</span></tt> points to a location that will hold a pointer to the new
|
|
pool.</p>
|
|
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena in which to create the pool.</p>
|
|
<p><tt class="docutils literal"><span class="pre">class</span></tt> is the <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool class</em></a> of the new pool.</p>
|
|
<p>Some pool classes require additional arguments to be passed to
|
|
<a class="reference internal" href="#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a>. See the documentation for the pool
|
|
class.</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 pool is created successfully,
|
|
or another <a class="reference internal" href="../glossary/r.html#term-result-code"><em class="xref std std-term">result code</em></a> otherwise.</p>
|
|
<p>The pool persists until it is destroyed by calling
|
|
<a class="reference internal" href="#mps_pool_destroy" title="mps_pool_destroy"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_destroy()</span></tt></a>.</p>
|
|
<div class="admonition-note admonition">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">There’s an alternative function <tt class="xref c c-func docutils literal"><span class="pre">pool_create_v()</span></tt> that
|
|
takes its extra arguments using the standard <a class="reference internal" href="../mmref/lang.html#term-c"><em class="xref std std-term">C</em></a>
|
|
<tt class="docutils literal"><span class="pre">va_list</span></tt> mechanism.</p>
|
|
</div>
|
|
</dd></dl>
|
|
|
|
<dl class="function">
|
|
<dt id="mps_pool_create_v">
|
|
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_pool_create_v</tt><big>(</big><a class="reference internal" href="#mps_pool_t" title="mps_pool_t">mps_pool_t</a><em> *pool_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em> arena</em>, <a class="reference internal" href="#mps_class_t" title="mps_class_t">mps_class_t</a><em> class</em>, va_list<em> args</em><big>)</big><a class="headerlink" href="#mps_pool_create_v" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>An alternative to <a class="reference internal" href="#mps_pool_create" title="mps_pool_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_create()</span></tt></a> that takes its extra
|
|
arguments using the standard <a class="reference internal" href="../mmref/lang.html#term-c"><em class="xref std std-term">C</em></a> <tt class="docutils literal"><span class="pre">va_list</span></tt> mechanism.</p>
|
|
</dd></dl>
|
|
|
|
<dl class="function">
|
|
<dt id="mps_pool_destroy">
|
|
void <tt class="descname">mps_pool_destroy</tt><big>(</big><a class="reference internal" href="#mps_pool_t" title="mps_pool_t">mps_pool_t</a><em> pool</em><big>)</big><a class="headerlink" href="#mps_pool_destroy" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>Destroy 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 to destroy.</p>
|
|
<p>This function checks the consistency of the pool, destroys the
|
|
pool’s internal control structures and causes the pool’s memory to
|
|
be returned to the <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> for reuse by other pools, or to
|
|
be returned to the operating system. Blocks allocated from the
|
|
pool may no longer be used.</p>
|
|
<p>It is an error to destroy a pool without first destroying all
|
|
<a class="reference internal" href="../glossary/a.html#term-allocation-point"><em class="xref std std-term">allocation points</em></a> and <a class="reference internal" href="../glossary/s.html#term-segregated-allocation-cache"><em class="xref std std-term">segregated allocation caches</em></a>
|
|
created in the pool.</p>
|
|
</dd></dl>
|
|
|
|
<div class="section" id="pool-classes">
|
|
<span id="index-1"></span><h2>4.1. Pool classes<a class="headerlink" href="#pool-classes" title="Permalink to this headline">¶</a></h2>
|
|
<p>Pools belong to <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool classes</em></a> that specify policies for how
|
|
their memory is managed. Some pools are <a class="reference internal" href="../glossary/m.html#term-manual-memory-management"><em class="xref std std-term">manually managed</em></a> (you must call <a class="reference internal" href="allocation.html#mps_free" title="mps_free"><tt class="xref c c-func docutils literal"><span class="pre">mps_free()</span></tt></a> to
|
|
return a block of memory to the pool) and others are
|
|
<a class="reference internal" href="../glossary/a.html#term-automatic-memory-management"><em class="xref std std-term">automatically managed</em></a> (the
|
|
<a class="reference internal" href="../glossary/g.html#term-garbage-collector"><em class="xref std std-term">garbage collector</em></a> reclaims <a class="reference internal" href="../glossary/u.html#term-unreachable"><em class="xref std std-term">unreachable</em></a> blocks).</p>
|
|
<p>See the <a class="reference internal" href="../pool/index.html#pool"><em>Pool reference</em></a> for a list of pool classes.</p>
|
|
<dl class="type">
|
|
<dt id="mps_class_t">
|
|
<tt class="descname">mps_class_t</tt><a class="headerlink" href="#mps_class_t" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>The type of <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool classes</em></a>.</p>
|
|
<div class="admonition-note admonition">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">This should really have been called <tt class="docutils literal"><span class="pre">mps_pool_class_t</span></tt> but
|
|
it is too late to change it now.</p>
|
|
</div>
|
|
</dd></dl>
|
|
|
|
</div>
|
|
<div class="section" id="pool-introspection">
|
|
<span id="index-2"></span><h2>4.2. Pool introspection<a class="headerlink" href="#pool-introspection" title="Permalink to this headline">¶</a></h2>
|
|
<dl class="function">
|
|
<dt id="mps_addr_pool">
|
|
<a class="reference internal" href="interface.html#mps_bool_t" title="mps_bool_t">mps_bool_t</a> <tt class="descname">mps_addr_pool</tt><big>(</big><a class="reference internal" href="#mps_pool_t" title="mps_pool_t">mps_pool_t</a><em> *pool_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em> arena</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em> addr</em><big>)</big><a class="headerlink" href="#mps_addr_pool" title="Permalink to this definition">¶</a></dt>
|
|
<dd><p>Determine the <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a> to which an address belongs.</p>
|
|
<p><tt class="docutils literal"><span class="pre">pool_o</span></tt> points to a location that will hold the address of the
|
|
pool, if one is found.</p>
|
|
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena whose pools will be considered.</p>
|
|
<p><tt class="docutils literal"><span class="pre">addr</span></tt> is the address.</p>
|
|
<p>If <tt class="docutils literal"><span class="pre">addr</span></tt> is the address of a location inside a block allocated
|
|
from a pool in <tt class="docutils literal"><span class="pre">arena</span></tt>, then update the location pointed to by
|
|
<tt class="docutils literal"><span class="pre">pool_o</span></tt> with the address of the pool, and return true.</p>
|
|
<p>If <tt class="docutils literal"><span class="pre">addr</span></tt> points to a location that is not managed by <tt class="docutils literal"><span class="pre">arena</span></tt>,
|
|
return false.</p>
|
|
<p>If neither of the above conditions is satisfied,
|
|
<a class="reference internal" href="#mps_addr_pool" title="mps_addr_pool"><tt class="xref c c-func docutils literal"><span class="pre">mps_addr_pool()</span></tt></a> may return either true or false.</p>
|
|
<div class="admonition-note admonition">
|
|
<p class="first admonition-title">Note</p>
|
|
<p>This function might return a false positive by returning true
|
|
if you ask about an address that happens to be inside memory
|
|
managed by a pool, but which is not inside a block allocated
|
|
by that pool. It never returns a false negative.</p>
|
|
<p class="last">The result from this function is valid only at the instant at
|
|
which the function returned. In some circumstances the result
|
|
may immediately become invalidated. For reliable results call
|
|
this function and interpret the result while 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>
|
|
</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. Pools</a><ul>
|
|
<li><a class="reference internal" href="#pool-classes">4.1. Pool classes</a></li>
|
|
<li><a class="reference internal" href="#pool-introspection">4.2. Pool introspection</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h4>Previous topic</h4>
|
|
<p class="topless"><a href="arena.html"
|
|
title="previous chapter">3. Arenas</a></p>
|
|
<h4>Next topic</h4>
|
|
<p class="topless"><a href="allocation.html"
|
|
title="next chapter">5. Allocation</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="allocation.html" title="5. Allocation"
|
|
>next</a> |</li>
|
|
<li class="right" >
|
|
<a href="arena.html" title="3. Arenas"
|
|
>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> |