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

248 lines
No EOL
18 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>5. 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="6. Allocation" href="allocation.html" />
<link rel="prev" title="4. 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="6. Allocation"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="arena.html" title="4. Arenas"
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="pools">
<span id="topic-pool"></span><span id="index-0"></span><h1>5. 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_k">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_pool_create_k</tt><big>(</big><a class="reference internal" href="#mps_pool_t" title="mps_pool_t">mps_pool_t</a><em>&nbsp;*pool_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="#mps_class_t" title="mps_class_t">mps_class_t</a><em>&nbsp;class</em>, <a class="reference internal" href="keyword.html#mps_arg_s" title="mps_arg_s">mps_arg_s</a><em>&nbsp;args[]</em><big>)</big><a class="headerlink" href="#mps_pool_create_k" 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><tt class="docutils literal"><span class="pre">args</span></tt> are <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword arguments</em></a> specific to the pool class.
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>
</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>&nbsp;*pool_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="#mps_class_t" title="mps_class_t">mps_class_t</a><em>&nbsp;class</em>, ...<big>)</big><a class="headerlink" href="#mps_pool_create" title="Permalink to this definition"></a></dt>
<dd><div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p class="last">Use <a class="reference internal" href="#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> instead: the <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword
arguments</em></a> interface is more reliable and produces better
error messages.</p>
</div>
<p>An alternative to <a class="reference internal" href="#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> 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> variable argument
list mechanism.</p>
</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>&nbsp;*pool_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="#mps_class_t" title="mps_class_t">mps_class_t</a><em>&nbsp;class</em>, va_list<em>&nbsp;args</em><big>)</big><a class="headerlink" href="#mps_pool_create_v" title="Permalink to this definition"></a></dt>
<dd><div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p class="last">Use <a class="reference internal" href="#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> instead: the <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword
arguments</em></a> interface is more reliable and produces better
error messages.</p>
</div>
<p>An alternative to <a class="reference internal" href="#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> 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>&nbsp;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&#8217;s internal control structures and causes the pool&#8217;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>5.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>5.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>&nbsp;*pool_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;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="#">5. Pools</a><ul>
<li><a class="reference internal" href="#pool-classes">5.1. Pool classes</a></li>
<li><a class="reference internal" href="#pool-introspection">5.2. Pool introspection</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="arena.html"
title="previous chapter">4. Arenas</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="allocation.html"
title="next chapter">6. Allocation</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="allocation.html" title="6. Allocation"
>next</a> |</li>
<li class="right" >
<a href="arena.html" title="4. Arenas"
>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