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
365 lines
No EOL
27 KiB
HTML
365 lines
No EOL
27 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>12. Finalization — 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="13. Location dependency" href="location.html" />
|
||
<link rel="prev" title="11. Messages" href="message.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="location.html" title="13. Location dependency"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="message.html" title="11. Messages"
|
||
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="finalization">
|
||
<span id="topic-finalization"></span><span id="index-0"></span><h1>12. Finalization<a class="headerlink" href="#finalization" title="Permalink to this headline">¶</a></h1>
|
||
<p>It is sometimes necessary to perform actions when a block of memory
|
||
<a class="reference internal" href="../glossary/d.html#term-dead"><em class="xref std std-term">dies</em></a>. For example, a block may represent the
|
||
acquisition of an external resource such as a file handle or a network
|
||
connection. When the block dies, the corresponding resource must be
|
||
released. This procedure is known as <a class="reference internal" href="../glossary/f.html#term-finalization"><em class="xref std std-term">finalization</em></a>.</p>
|
||
<p>A block requiring finalization must be registered by calling <a class="reference internal" href="#mps_finalize" title="mps_finalize"><tt class="xref c c-func docutils literal"><span class="pre">mps_finalize()</span></tt></a>:</p>
|
||
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_addr_t</span> <span class="n">ref</span> <span class="o">=</span> <span class="n">block_requiring_finalization</span><span class="p">;</span>
|
||
<span class="n">mps_finalize</span><span class="p">(</span><span class="n">arena</span><span class="p">,</span> <span class="o">&</span><span class="n">ref</span><span class="p">);</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>A block that been registered for finalization becomes <em>finalizable</em> as
|
||
soon as the <a class="reference internal" href="../glossary/g.html#term-garbage-collector"><em class="xref std std-term">garbage collector</em></a> observes that it would otherwise
|
||
be <a class="reference internal" href="../glossary/r.html#term-reclaim"><em class="xref std std-term">reclaimed</em></a> (that is, the only thing keeping it alive is the
|
||
fact that it needs to be finalized). If a block is finalizable the MPS
|
||
may choose to finalize it (by posting a finalization message: see
|
||
below) at <em>any</em> future time.</p>
|
||
<div class="admonition-note admonition">
|
||
<p class="first admonition-title">Note</p>
|
||
<p class="last">This means that a block that was determined to be finalizable, but
|
||
then became unconditionally <a class="reference internal" href="../glossary/l.html#term-live"><em class="xref std std-term">live</em></a> by the creation of a new
|
||
<a class="reference internal" href="../glossary/s.html#term-strong-reference"><em class="xref std std-term">strong reference</em></a> to it, may still be finalized.</p>
|
||
</div>
|
||
<p><a class="reference internal" href="../glossary/w.html#term-weak-reference-1"><em class="xref std std-term">Weak references<sup>(1)</sup></em></a> do not prevent blocks
|
||
from being finalized. At the point that a block is finalized, weak
|
||
references will still validly refer to the block. The fact that a
|
||
block is registered for finalization prevents weak references to that
|
||
block from being <a class="reference internal" href="../glossary/s.html#term-splat"><em class="xref std std-term">splatted</em></a>. See <a class="reference internal" href="weak.html#topic-weak"><em>Weak references</em></a>.</p>
|
||
<p>The Memory Pool System finalizes a block by posting a <em>finalization
|
||
message</em> to the <a class="reference internal" href="../glossary/m.html#term-message-queue"><em class="xref std std-term">message queue</em></a> of the <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> in which
|
||
the block was allocated.</p>
|
||
<div class="admonition-note admonition">
|
||
<p class="first admonition-title">Note</p>
|
||
<p class="last">This design avoids the problems that can result from the
|
||
<a class="reference internal" href="../glossary/g.html#term-garbage-collector"><em class="xref std std-term">garbage collector</em></a> calling a function in the client program
|
||
to do the finalization. In such an implementation, the client
|
||
program’s finalization code may end up running concurrently with
|
||
other code that accesses the underlying resource, and so access to
|
||
the resource need to be guarded with a lock, but then an unlucky
|
||
scheduling of finalization can result in deadlock. See <a class="reference internal" href="../mmref/bib.html#boehm02"><em>Boehm
|
||
(2002)</em></a> for a detailed discussion of this issue.</p>
|
||
</div>
|
||
<p>The <a class="reference internal" href="../glossary/m.html#term-message-type"><em class="xref std std-term">message type</em></a> of finalization messages is
|
||
<a class="reference internal" href="#mps_message_type_finalization" title="mps_message_type_finalization"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_type_finalization()</span></tt></a>, and the client program must
|
||
enable the posting of these messages by calling
|
||
<a class="reference internal" href="message.html#mps_message_type_enable" title="mps_message_type_enable"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_type_enable()</span></tt></a> before any block becomes
|
||
finalizable:</p>
|
||
<div class="highlight-c"><div class="highlight"><pre><span class="n">mps_message_type_enable</span><span class="p">(</span><span class="n">arena</span><span class="p">,</span> <span class="n">mps_message_type_finalization</span><span class="p">());</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>When a finalization message has been retrieved from the message queue
|
||
by calling <a class="reference internal" href="message.html#mps_message_get" title="mps_message_get"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_get()</span></tt></a>, the finalization reference may
|
||
be accessed by calling <a class="reference internal" href="#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>. The
|
||
finalization message keeps the block alive until it is discarded by
|
||
calling <a class="reference internal" href="message.html#mps_message_discard" title="mps_message_discard"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_discard()</span></tt></a>.</p>
|
||
<div class="admonition-note admonition">
|
||
<p class="first admonition-title">Note</p>
|
||
<p>The client program may choose to keep the finalized block alive by
|
||
keeping a strong reference to the finalized object after
|
||
discarding the finalization message.</p>
|
||
<p>This process is known as <a class="reference internal" href="../glossary/r.html#term-resurrection"><em class="xref std std-term">resurrection</em></a> and in some
|
||
finalization systems requires special handling, but in the MPS
|
||
this just is just the usual result of the rule that strong
|
||
references keep objects alive.</p>
|
||
<p class="last">It is fine to re-register a block for finalization after
|
||
retrieving its finalization message from the message queue. This
|
||
will cause it to be finalized again should all strong references
|
||
disappear again.</p>
|
||
</div>
|
||
<p>See <a class="reference internal" href="message.html#topic-message"><em>Messages</em></a> for details of the message mechanism.</p>
|
||
<div class="section" id="multiple-finalizations">
|
||
<span id="index-1"></span><h2>12.1. Multiple finalizations<a class="headerlink" href="#multiple-finalizations" title="Permalink to this headline">¶</a></h2>
|
||
<p>A block may be registered for finalization multiple times. A block
|
||
that has been registered for finalization <em>n</em> times will be finalized
|
||
at most <em>n</em> times.</p>
|
||
<p>This may mean that there are multiple finalization messages on the
|
||
queue at the same time, or it may not (it may be necessary for the
|
||
client program to discard previous finalization messages for a block
|
||
before a new finalization messages for that block are posted to the
|
||
message queue). The MPS provides no guarantees either way: a client
|
||
program that registers the same block multiple times must cope with
|
||
either behaviour.</p>
|
||
</div>
|
||
<div class="section" id="cautions">
|
||
<span id="topic-finalization-cautions"></span><span id="index-2"></span><h2>12.2. Cautions<a class="headerlink" href="#cautions" title="Permalink to this headline">¶</a></h2>
|
||
<ol class="arabic">
|
||
<li><p class="first">Don’t rely on finalization for your program to work. Treat it as an
|
||
optimization that enables the freeing of resources that the
|
||
garbage collector can prove are unreachable.</p>
|
||
</li>
|
||
<li><p class="first">The MPS provides no guarantees about the promptness of
|
||
finalization. The MPS does not finalize a block until it
|
||
determines that the block is finalizable, which may require a full
|
||
garbage collection in the worst case, and such a collection may
|
||
not <a class="reference internal" href="collection.html#topic-collection-schedule"><em>scheduled</em></a> for some time. Or
|
||
the block may never become finalizable because it is incorrectly
|
||
determined to be reachable due to an <a class="reference internal" href="../glossary/a.html#term-ambiguous-reference"><em class="xref std std-term">ambiguous reference</em></a>
|
||
pointing to it. Or the block may never become finalizable because
|
||
it remains reachable through a reference, even if that reference
|
||
might never be used.</p>
|
||
</li>
|
||
<li><p class="first">Even when blocks are finalized in a reasonably timely fashion, the
|
||
client needs to process the finalization messages in time to avoid
|
||
the resource running out. For example, in the Scheme interpreter,
|
||
finalization messages are only processed at the end of the
|
||
read–eval–print loop, so a program that opens many files may run
|
||
out of handles even though the associated objects are all
|
||
finalizable, as shown here:</p>
|
||
<div class="highlight-none"><div class="highlight"><pre>MPS Toy Scheme Example
|
||
9960, 0> (define (repeat n f _) (if (eqv? n 0) '() (repeat (- n 1) f (f))))
|
||
repeat
|
||
10840, 0> (repeat 300 (lambda () (open-input-file "scheme.c")) 0)
|
||
open-input-file: cannot open input file
|
||
</pre></div>
|
||
</div>
|
||
<p>A less naïve interpreter might process finalization messages on a
|
||
more regular schedule, or might take emergency action in the event
|
||
of running out of open file handles by carrying out a full garbage
|
||
collection and processing any finalization messages that are
|
||
posted as a result.</p>
|
||
<p>If you are designing a programming language then it is generally a
|
||
good idea to provide the programmer with a mechanism for ensuring
|
||
prompt release of scarce resources. For example, Scheme provides
|
||
the <tt class="docutils literal"><span class="pre">(with-input-from-file)</span></tt> procedure which specifies that the
|
||
created port has <a class="reference internal" href="../glossary/d.html#term-dynamic-extent"><em class="xref std std-term">dynamic extent</em></a> (and so can be closed as
|
||
soon as the procedure exits).</p>
|
||
</li>
|
||
<li><p class="first">The MPS does not finalize objects in the context of
|
||
<a class="reference internal" href="arena.html#mps_arena_destroy" title="mps_arena_destroy"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_destroy()</span></tt></a> or <a class="reference internal" href="pool.html#mps_pool_destroy" title="mps_pool_destroy"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_destroy()</span></tt></a>.
|
||
<a class="reference internal" href="pool.html#mps_pool_destroy" title="mps_pool_destroy"><tt class="xref c c-func docutils literal"><span class="pre">mps_pool_destroy()</span></tt></a> should therefore not be invoked on pools
|
||
containing objects registered for finalization.</p>
|
||
<div class="admonition-note admonition">
|
||
<p class="first admonition-title">Note</p>
|
||
<p>Under normal circumstances, finalization code can assume that
|
||
objects referenced by the object being finalized (“object F”)
|
||
have themselves not yet been finalized. (Because object F is
|
||
keeping them alive.) If finalization code is run at program
|
||
exit, this assumption is no longer true. It is much more
|
||
difficult to write correct code if it has to run under both
|
||
circumstances.</p>
|
||
<p class="last">This is why Java’s <tt class="docutils literal"><span class="pre">System.runFinalizersOnExit</span></tt> is
|
||
deprecated. See Appendix A of <a class="reference internal" href="../mmref/bib.html#boehm02"><em>Boehm (2002)</em></a>
|
||
for a discussion of this problem.</p>
|
||
</div>
|
||
</li>
|
||
</ol>
|
||
<ol class="arabic simple" start="4">
|
||
<li>Not all <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool classes</em></a> support finalization. In general, only
|
||
pools that manage objects whose liveness is determined by garbage
|
||
collection do so. See the <a class="reference internal" href="../pool/index.html#pool"><em>Pool reference</em></a>.</li>
|
||
</ol>
|
||
</div>
|
||
<div class="section" id="finalization-interface">
|
||
<span id="index-3"></span><h2>12.3. Finalization interface<a class="headerlink" href="#finalization-interface" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="function">
|
||
<dt id="mps_finalize">
|
||
<a class="reference internal" href="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="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> *ref_p</em><big>)</big><a class="headerlink" href="#mps_finalize" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Register a <a class="reference internal" href="../glossary/b.html#term-block"><em class="xref std std-term">block</em></a> for <a class="reference internal" href="../glossary/f.html#term-finalization"><em class="xref std std-term">finalization</em></a>.</p>
|
||
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena in which the block lives.</p>
|
||
<p><tt class="docutils literal"><span class="pre">ref_p</span></tt> points to a <a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">reference</em></a> to the block to be
|
||
registered for finalization.</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 successful, or another
|
||
<a class="reference internal" href="../glossary/r.html#term-result-code"><em class="xref std std-term">result code</em></a> if not.</p>
|
||
<p>This function registers the block pointed to by <tt class="docutils literal"><span class="pre">*ref_p</span></tt> for
|
||
finalization. This block must have been allocated from a
|
||
<a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a> in <tt class="docutils literal"><span class="pre">arena</span></tt>. Violations of this constraint may not
|
||
be checked by the MPS, and may be unsafe, causing the MPS to crash
|
||
in undefined ways.</p>
|
||
<div class="admonition-note admonition">
|
||
<p class="first admonition-title">Note</p>
|
||
<p class="last">This function receives a pointer to a reference. This is to
|
||
avoid placing the restriction on the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a>
|
||
that the C call stack be a <a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">root</em></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="mps_definalize">
|
||
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_definalize</tt><big>(</big><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> *ref_p</em><big>)</big><a class="headerlink" href="#mps_definalize" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Deregister a <a class="reference internal" href="../glossary/b.html#term-block"><em class="xref std std-term">block</em></a> for <a class="reference internal" href="../glossary/f.html#term-finalization"><em class="xref std std-term">finalization</em></a>.</p>
|
||
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena in which the block lives.</p>
|
||
<p><tt class="docutils literal"><span class="pre">ref_p</span></tt> points to a <a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">reference</em></a> to the block to be
|
||
deregistered for finalization.</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 successful, or
|
||
<a class="reference internal" href="error.html#MPS_RES_FAIL" title="MPS_RES_FAIL"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_FAIL</span></tt></a> if the block was not previously registered
|
||
for finalization.</p>
|
||
<div class="admonition-note admonition">
|
||
<p class="first admonition-title">Note</p>
|
||
<p class="last">This function receives a pointer to a reference. This is to
|
||
avoid placing the restriction on the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a>
|
||
that the C call stack be a <a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">root</em></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="finalization-messages">
|
||
<span id="index-4"></span><h2>12.4. Finalization messages<a class="headerlink" href="#finalization-messages" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="function">
|
||
<dt id="mps_message_type_finalization">
|
||
<a class="reference internal" href="message.html#mps_message_type_t" title="mps_message_type_t">mps_message_type_t</a> <tt class="descname">mps_message_type_finalization</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_message_type_finalization" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the <a class="reference internal" href="../glossary/m.html#term-message-type"><em class="xref std std-term">message type</em></a> of finalization messages.</p>
|
||
<p>Finalization messages are used by the MPS to implement
|
||
<a class="reference internal" href="../glossary/f.html#term-finalization"><em class="xref std std-term">finalization</em></a>. When the MPS detects that a block that has
|
||
been registered for finalization (by calling
|
||
<a class="reference internal" href="#mps_finalize" title="mps_finalize"><tt class="xref c c-func docutils literal"><span class="pre">mps_finalize()</span></tt></a>) is finalizable, it finalizes it by posting
|
||
a <a class="reference internal" href="../glossary/m.html#term-message"><em class="xref std std-term">message</em></a> of this type.</p>
|
||
<p>Note that there might be delays between the block becoming
|
||
finalizable, the MPS detecting that, and the message being
|
||
posted.</p>
|
||
<p>In addition to the usual methods applicable to messages,
|
||
finalization messages support the
|
||
<a class="reference internal" href="#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> method which returns a
|
||
reference to the block that was registered for finalization.</p>
|
||
<div class="admonition-see-also admonition seealso">
|
||
<p class="first admonition-title">See also</p>
|
||
<p class="last"><a class="reference internal" href="message.html#topic-message"><em>Messages</em></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<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="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em> *ref_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="message.html#mps_message_t" title="mps_message_t">mps_message_t</a><em> message</em><big>)</big><a class="headerlink" href="#mps_message_finalization_ref" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the finalization reference for a finalization message.</p>
|
||
<p><tt class="docutils literal"><span class="pre">ref_o</span></tt> points to a location that will hold the finalization
|
||
reference.</p>
|
||
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> which posted the message.</p>
|
||
<p><tt class="docutils literal"><span class="pre">message</span></tt> is a message retrieved by <a class="reference internal" href="message.html#mps_message_get" title="mps_message_get"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_get()</span></tt></a> and
|
||
not yet discarded. It must be a finalization message: see
|
||
<a class="reference internal" href="#mps_message_type_finalization" title="mps_message_type_finalization"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_type_finalization()</span></tt></a>.</p>
|
||
<p>The reference returned by this method is a reference to the block
|
||
that was originally registered for <a class="reference internal" href="../glossary/f.html#term-finalization"><em class="xref std std-term">finalization</em></a> by a call
|
||
to <a class="reference internal" href="#mps_finalize" title="mps_finalize"><tt class="xref c c-func docutils literal"><span class="pre">mps_finalize()</span></tt></a>.</p>
|
||
<div class="admonition-note admonition">
|
||
<p class="first admonition-title">Note</p>
|
||
<p>The reference returned is subject to the normal constraints,
|
||
such as might be imposed by a <a class="reference internal" href="../glossary/m.html#term-moving-garbage-collector"><em class="xref std std-term">moving</em></a> collection, if appropriate. For this reason, it is
|
||
stored into the location pointed to by <tt class="docutils literal"><span class="pre">ref_o</span></tt> in order to
|
||
enable the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> to place it directly into
|
||
scanned memory, without imposing the restriction that the C
|
||
stack be a <a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">root</em></a>.</p>
|
||
<p class="last">The message itself is not affected by invoking this method.
|
||
Until the client program calls <a class="reference internal" href="message.html#mps_message_discard" title="mps_message_discard"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_discard()</span></tt></a>
|
||
to discard the message, it will refer to the object and
|
||
prevent its reclamation.</p>
|
||
</div>
|
||
<div class="admonition-see-also admonition seealso">
|
||
<p class="first admonition-title">See also</p>
|
||
<p class="last"><a class="reference internal" href="message.html#topic-message"><em>Messages</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="#">12. Finalization</a><ul>
|
||
<li><a class="reference internal" href="#multiple-finalizations">12.1. Multiple finalizations</a></li>
|
||
<li><a class="reference internal" href="#cautions">12.2. Cautions</a></li>
|
||
<li><a class="reference internal" href="#finalization-interface">12.3. Finalization interface</a></li>
|
||
<li><a class="reference internal" href="#finalization-messages">12.4. Finalization messages</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="message.html"
|
||
title="previous chapter">11. Messages</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="location.html"
|
||
title="next chapter">13. Location dependency</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="location.html" title="13. Location dependency"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="message.html" title="11. Messages"
|
||
>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> |