mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-01-12 22:40:46 -08:00
Code Issues Projects Releases Wiki Activity
emacs/mps/manual/html/design/finalize.html
Gareth Rees c5f77afc19 Bring html up to date for the mps manual. 
Copied from Perforce
 Change: 181433
 ServerID: perforce.ravenbrook.com
2013-04-24 12:21:37 +01:00

239 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>8. Finalization &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="Design" href="index.html" />
<link rel="next" title="9. The generic fix function" href="fix.html" />
<link rel="prev" title="7. Configuration" href="config.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="fix.html" title="9. The generic fix function"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="config.html" title="7. Configuration"
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">Design</a> &raquo;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="finalization">
<span id="design.mps.finalize"></span><h1>8. Finalization<a class="headerlink" href="#finalization" title="Permalink to this headline"></a></h1>
<div class="section" id="overview">
<h2>8.1. Overview<a class="headerlink" href="#overview" title="Permalink to this headline"></a></h2>
<p>Finalization is implemented internally using the Guardian Pool Class
(design.mps.poolmrg). Objects can be registered for
finalization using an interface function (called
<a class="reference internal" href="../topic/finalization.html#mps_finalize" title="mps_finalize"><tt class="xref c c-func docutils literal"><span class="pre">mps_finalize()</span></tt></a>). Notification of finalization is given to the
client via the messaging interface. <tt class="xref c c-type docutils literal"><span class="pre">PoolClassMRG</span></tt>
(design.mps.poolmrg) implements a Message Class which
implements the finalization messages.</p>
</div>
<div class="section" id="history">
<h2>8.2. History<a class="headerlink" href="#history" title="Permalink to this headline"></a></h2>
<p><span class="target" id="design.mps.finalize.hist.0"></span><a class="mpstag reference internal" href="#design.mps.finalize.hist.0">.hist.0:</a> Incomplete design. David Jones, 1997-02-14.</p>
<p><span class="target" id="design.mps.finalize.hist.1"></span><a class="mpstag reference internal" href="#design.mps.finalize.hist.1">.hist.1:</a> Converted from MMInfo database design document.
Richard Brooksby, 2002-06-07.</p>
<p><span class="target" id="design.mps.finalize.hist.2"></span><a class="mpstag reference internal" href="#design.mps.finalize.hist.2">.hist.2:</a> Converted to reStructuredText. Gareth Rees,
2013-04-13.</p>
</div>
<div class="section" id="requirements">
<h2>8.3. Requirements<a class="headerlink" href="#requirements" title="Permalink to this headline"></a></h2>
<p><span class="target" id="design.mps.finalize.req"></span><a class="mpstag reference internal" href="#design.mps.finalize.req">.req:</a> Historically only Dylan had requirements for
finalization, see req.dylan.fun.final. Now (2003-02-19)
Configura have requirements for finalization. Happily they are very
similar.</p>
</div>
<div class="section" id="architecture">
<h2>8.4. Architecture<a class="headerlink" href="#architecture" title="Permalink to this headline"></a></h2>
<div class="section" id="external-interface">
<h3>8.4.1. External interface<a class="headerlink" href="#external-interface" title="Permalink to this headline"></a></h3>
<dl class="function">
<dt id="mps_finalize">
<a class="reference internal" href="../topic/error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_finalize</tt><big>(</big><a class="reference internal" href="../topic/arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="../topic/interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;obj</em><big>)</big><a class="headerlink" href="#mps_finalize" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<p><span class="target" id="design.mps.finalize.if.register"></span><a class="mpstag reference internal" href="#design.mps.finalize.if.register">.if.register:</a> Increases the number of times that the object
located at <tt class="docutils literal"><span class="pre">obj</span></tt> has been registered for finalization by one. The
object must have been allocated from the arena (space). Any
finalization messages that are created for this object will appear on
the arena&#8217;s message queue. The MPS will attempt to finalize the object
that number of times.</p>
<dl class="function">
<dt id="mps_definalize">
void <tt class="descname">mps_definalize</tt><big>(</big><a class="reference internal" href="../topic/arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="../topic/interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;obj</em><big>)</big><a class="headerlink" href="#mps_definalize" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<p><span class="target" id="design.mps.finalize.if.deregister"></span><a class="mpstag reference internal" href="#design.mps.finalize.if.deregister">.if.deregister:</a> <a class="reference internal" href="../topic/finalization.html#mps_definalize" title="mps_definalize"><tt class="xref c c-func docutils literal"><span class="pre">mps_definalize()</span></tt></a> reduces the number
of times that the object located at <tt class="docutils literal"><span class="pre">obj</span></tt> has been registered for
finalization by one. It is an error to definalize an object that has
not been registered for finalization.</p>
<p><span class="target" id="design.mps.finalize.if.deregister.not"></span><a class="mpstag reference internal" href="#design.mps.finalize.if.deregister.not">.if.deregister.not:</a> At the moment (1997-08-20) <a class="reference internal" href="../topic/finalization.html#mps_definalize" title="mps_definalize"><tt class="xref c c-func docutils literal"><span class="pre">mps_definalize()</span></tt></a> is not implemented.</p>
<dl class="function">
<dt id="mps_message_finalization_ref">
void <tt class="descname">mps_message_finalization_ref</tt><big>(</big><a class="reference internal" href="../topic/interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;*mps_addr_return</em>, <a class="reference internal" href="../topic/arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;mps_arena</em>, <a class="reference internal" href="../topic/message.html#mps_message_t" title="mps_message_t">mps_message_t</a><em>&nbsp;mps_message</em><big>)</big><a class="headerlink" href="#mps_message_finalization_ref" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<p><span class="target" id="design.mps.finalize.if.get-ref"></span><a class="mpstag reference internal" href="#design.mps.finalize.if.get-ref">.if.get-ref:</a> <a class="reference internal" href="../topic/finalization.html#mps_message_finalization_ref" title="mps_message_finalization_ref"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_finalization_ref()</span></tt></a> returns
the reference to the finalized object stored in the finalization
message.</p>
</div>
</div>
<div class="section" id="implementation">
<h2>8.5. Implementation<a class="headerlink" href="#implementation" title="Permalink to this headline"></a></h2>
<p><span class="target" id="design.mps.finalize.int.over"></span><a class="mpstag reference internal" href="#design.mps.finalize.int.over">.int.over:</a> Registering an object for finalization corresponds
to allocating a reference of rank FINAL to that object. This reference
is allocated in a guardian object in a pool of <tt class="xref c c-type docutils literal"><span class="pre">PoolClassMRG</span></tt>
(see design.mps.poolmrg).</p>
<p><span class="target" id="design.mps.finalize.int.arena.struct"></span><a class="mpstag reference internal" href="#design.mps.finalize.int.arena.struct">.int.arena.struct:</a> The MRG pool used for managing final
references is kept in the Arena (Space), referred to as the &#8220;final
pool&#8221;.</p>
<p><span class="target" id="design.mps.finalize.int.arena.lazy"></span><a class="mpstag reference internal" href="#design.mps.finalize.int.arena.lazy">.int.arena.lazy:</a> The pool is lazily created. It will not be
created until the first object is registered for finalization.</p>
<p><span class="target" id="design.mps.finalize.int.arena.flag"></span><a class="mpstag reference internal" href="#design.mps.finalize.int.arena.flag">.int.arena.flag:</a> There is a flag in the Arena that indicates
whether the final pool has been created yet or not.</p>
<dl class="function">
<dt id="ArenaFinalize">
<a class="reference internal" href="type.html#Res" title="Res">Res</a> <tt class="descname">ArenaFinalize</tt><big>(</big>Arena<em>&nbsp;arena</em>, <a class="reference internal" href="type.html#Ref" title="Ref">Ref</a><em>&nbsp;addr</em><big>)</big><a class="headerlink" href="#ArenaFinalize" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<p><span class="target" id="design.mps.finalize.int.finalize.create"></span><a class="mpstag reference internal" href="#design.mps.finalize.int.finalize.create">.int.finalize.create:</a> Creates the final pool if it has not
been created yet.</p>
<p><span class="target" id="design.mps.finalize.int.finalize.alloc"></span><a class="mpstag reference internal" href="#design.mps.finalize.int.finalize.alloc">.int.finalize.alloc:</a> Allocates a guardian in the final pool.</p>
<p><span class="target" id="design.mps.finalize.int.finalize.write"></span><a class="mpstag reference internal" href="#design.mps.finalize.int.finalize.write">.int.finalize.write:</a> Writes a reference to the object into
the guardian object.</p>
<p><span class="target" id="design.mps.finalize.int.finalize.all"></span><a class="mpstag reference internal" href="#design.mps.finalize.int.finalize.all">.int.finalize.all:</a> That&#8217;s all.</p>
<p><span class="target" id="design.mps.finalize.int.finalize.error"></span><a class="mpstag reference internal" href="#design.mps.finalize.int.finalize.error">.int.finalize.error:</a> If either the
creation of the pool or the allocation of the object fails then the error will
be reported back to the caller.</p>
<p><span class="target" id="design.mps.finalize.int.finalize.error.no-unwind"></span><a class="mpstag reference internal" href="#design.mps.finalize.int.finalize.error.no-unwind">.int.finalize.error.no-unwind:</a> This function does not need to
do any unwinding in the error cases because the creation of the pool
is not something that needs to be undone.</p>
<p><span class="target" id="design.mps.finalize.int.arena-destroy.empty"></span><a class="mpstag reference internal" href="#design.mps.finalize.int.arena-destroy.empty">.int.arena-destroy.empty:</a> <tt class="xref c c-func docutils literal"><span class="pre">ArenaDestroy()</span></tt> empties the
message queue by calling <tt class="xref c c-func docutils literal"><span class="pre">MessageEmpty()</span></tt>.</p>
<p><span class="target" id="design.mps.finalize.int.arena-destroy.final-pool"></span><a class="mpstag reference internal" href="#design.mps.finalize.int.arena-destroy.final-pool">.int.arena-destroy.final-pool:</a> If the final pool has been
created then <tt class="xref c c-func docutils literal"><span class="pre">ArenaDestroy()</span></tt> destroys the final pool.</p>
<p><span class="target" id="design.mps.finalize.access"></span><a class="mpstag reference internal" href="#design.mps.finalize.access">.access:</a> <a class="reference internal" href="../topic/finalization.html#mps_message_finalization_ref" title="mps_message_finalization_ref"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_finalization_ref()</span></tt></a> needs to
access the finalization message to retrieve the reference and then
write it to where the client asks. This must be done carefully, in
order to avoid breaking the invariants or creating a hidden root.</p>
<p><span class="target" id="design.mps.finalize.access.invariants"></span><a class="mpstag reference internal" href="#design.mps.finalize.access.invariants">.access.invariants:</a> We protect the invariants by using
special routines <tt class="xref c c-func docutils literal"><span class="pre">ArenaRead()</span></tt> and <tt class="xref c c-func docutils literal"><span class="pre">ArenaPoke()</span></tt> to read
and write the reference. This works as long as there&#8217;s no
write-barrier collection. [Instead of <tt class="xref c c-func docutils literal"><span class="pre">ArenaPoke()</span></tt>, we could
put in an <tt class="xref c c-func docutils literal"><span class="pre">ArenaWrite()</span></tt> that would be identical to
<tt class="xref c c-func docutils literal"><span class="pre">ArenaPoke()</span></tt>, except for AVERring the invariant (or it can
just AVER there are no busy traces unflipped). When we get
write-barrier collection, we could change it to do the real thing, but
in the absence of a write-barrier, it&#8217;s functionally identical to
<tt class="xref c c-func docutils literal"><span class="pre">ArenaPoke()</span></tt>. Pekka 1997-12-09]</p>
</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="#">8. Finalization</a><ul>
<li><a class="reference internal" href="#overview">8.1. Overview</a></li>
<li><a class="reference internal" href="#history">8.2. History</a></li>
<li><a class="reference internal" href="#requirements">8.3. Requirements</a></li>
<li><a class="reference internal" href="#architecture">8.4. Architecture</a><ul>
<li><a class="reference internal" href="#external-interface">8.4.1. External interface</a></li>
</ul>
</li>
<li><a class="reference internal" href="#implementation">8.5. Implementation</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="config.html"
title="previous chapter">7. Configuration</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="fix.html"
title="next chapter">9. The generic fix function</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="fix.html" title="9. The generic fix function"
>next</a> |</li>
<li class="right" >
<a href="config.html" title="7. Configuration"
>previous</a> |</li>
<li><a href="../index.html">Memory Pool System 1.111.0 documentation</a> &raquo;</li>
<li><a href="index.html" >Design</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