mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-26 15:21:51 -08:00
Code Issues Projects Releases Wiki Activity
emacs/mps/manual/html/topic/message.html
Gareth Rees 28419106ca Build html version of the manual in manual/html. 
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
2012-11-05 17:18:50 +00:00

408 lines
No EOL
35 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>11. Messages &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="12. Finalization" href="finalization.html" />
<link rel="prev" title="10. Garbage collection" href="collection.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="finalization.html" title="12. Finalization"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="collection.html" title="10. Garbage collection"
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="messages">
<span id="topic-message"></span><span id="index-0"></span><h1>11. Messages<a class="headerlink" href="#messages" title="Permalink to this headline"></a></h1>
<p>The MPS sometimes needs to communicate with the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a>
about events which occur <a class="reference internal" href="../glossary/a.html#term-asynchronous-garbage-collector"><em class="xref std std-term">asynchronously</em></a>, and so information cannot be returned as function call
results.</p>
<p><em>Messages</em> are the mechanism for this asynchronous communication,
implemented in the form of a <a class="reference internal" href="../glossary/m.html#term-message-queue"><em class="xref std std-term">message queue</em></a> attached to each
<a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a>.</p>
<p>The client program must enable each message type that they are
prepared to handle, by calling <a class="reference internal" href="#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>. Then
it must poll the message queue at regular intervals when it is
convenient to do so, calling <a class="reference internal" href="#mps_message_get" title="mps_message_get"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_get()</span></tt></a> to retrieve
each message from the queue, and then calling
<a class="reference internal" href="#mps_message_discard" title="mps_message_discard"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_discard()</span></tt></a> when it is done with it.</p>
<p>Messages are thus <a class="reference internal" href="../glossary/m.html#term-manual-memory-management"><em class="xref std std-term">manually managed</em></a>:
if the client program enables one or more message types, and then
neglects to poll the message queue or neglects to discard the messages
it retrieved, then messages will <a class="reference internal" href="../glossary/m.html#term-memory-leak"><em class="xref std std-term">leak</em></a>.</p>
<p>There is no requirement on the client program to retrieve and discard
messages promptly. However, a client program that allows the number of
garbage collection (or garbage collection start) messages on the
message queue to grow without limit will eventually find that new
garbage collections no longer start until some of these messages are
retrieved and discarded.</p>
<div class="section" id="finalization-messages">
<span id="index-1"></span><h2>11.1. Finalization messages<a class="headerlink" href="#finalization-messages" title="Permalink to this headline"></a></h2>
<p><a class="reference internal" href="../glossary/f.html#term-finalization"><em class="xref std std-term">Finalization</em></a> is implemented by posting a finalization message
(of type <a class="reference internal" href="finalization.html#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>) to the arena&#8217;s
message queue. This allows the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> to perform the
finalization at a convenient time and so avoid synchronization
difficulties.</p>
<p>The block is not actually reclaimed until the finalization message is
removed from the message queue and discarded, by calling
<a class="reference internal" href="#mps_message_get" title="mps_message_get"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_get()</span></tt></a> followed by <a class="reference internal" href="#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>
<p>See <a class="reference internal" href="finalization.html#topic-finalization"><em>Finalization</em></a>.</p>
</div>
<div class="section" id="example-interactive-chatter">
<span id="index-2"></span><h2>11.2. Example: interactive chatter<a class="headerlink" href="#example-interactive-chatter" title="Permalink to this headline"></a></h2>
<p>The toy Scheme interpreter enables garbage collection messages when
started in interactive mode:</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_gc</span><span class="p">());</span>
<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_gc_start</span><span class="p">());</span>
</pre></div>
</div>
<p>Then, after every interactive command finishes, it reads these
messages from the message queue and prints a description of the
contents of each one:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">void</span> <span class="nf">mps_chat</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">mps_message_type_t</span> <span class="n">type</span><span class="p">;</span>
<span class="k">while</span> <span class="p">(</span><span class="n">mps_message_queue_type</span><span class="p">(</span><span class="o">&amp;</span><span class="n">type</span><span class="p">,</span> <span class="n">arena</span><span class="p">))</span> <span class="p">{</span>
<span class="n">mps_message_t</span> <span class="n">message</span><span class="p">;</span>
<span class="n">mps_bool_t</span> <span class="n">b</span><span class="p">;</span>
<span class="n">b</span> <span class="o">=</span> <span class="n">mps_message_get</span><span class="p">(</span><span class="o">&amp;</span><span class="n">message</span><span class="p">,</span> <span class="n">arena</span><span class="p">,</span> <span class="n">type</span><span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="n">b</span><span class="p">);</span> <span class="cm">/* we just checked there was one */</span>
<span class="k">if</span> <span class="p">(</span><span class="n">type</span> <span class="o">==</span> <span class="n">mps_message_type_gc_start</span><span class="p">())</span> <span class="p">{</span>
<span class="n">printf</span><span class="p">(</span><span class="s">&quot;Collection started.</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">);</span>
<span class="n">printf</span><span class="p">(</span><span class="s">&quot; Why: %s</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span> <span class="n">mps_message_gc_start_why</span><span class="p">(</span><span class="n">arena</span><span class="p">,</span> <span class="n">message</span><span class="p">));</span>
<span class="n">printf</span><span class="p">(</span><span class="s">&quot; Clock: %lu</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="kt">long</span><span class="p">)</span><span class="n">mps_message_clock</span><span class="p">(</span><span class="n">arena</span><span class="p">,</span> <span class="n">message</span><span class="p">));</span>
<span class="k">if</span> <span class="p">(</span><span class="n">type</span> <span class="o">==</span> <span class="n">mps_message_type_gc</span><span class="p">())</span> <span class="p">{</span>
<span class="cm">/* ... and so on for other message types ... */</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
<span class="n">printf</span><span class="p">(</span><span class="s">&quot;Unknown message from MPS!</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">);</span>
<span class="p">}</span>
<span class="n">mps_message_discard</span><span class="p">(</span><span class="n">arena</span><span class="p">,</span> <span class="n">message</span><span class="p">);</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Here&#8217;s how this looks in operation:</p>
<div class="highlight-none"><div class="highlight"><pre>MPS Toy Scheme Example
9960, 0&gt; (define (make-list n e) (if (eqv? n 0) &#39;() (cons e (make-list (- n 1) e))))
make-list
10824, 0&gt; (length (make-list 1000 #t))
1000
Collection started.
Why: Generation 0 of a chain has reached capacity: start a minor collection.
Clock: 6649
507408, 1&gt; (length (make-list 200 #f))
200
Collection finished.
live 112360
condemned 196600
not_condemned 0
clock: 18431
607192, 1&gt; Bye.
</pre></div>
</div>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p>This kind of interative &#8220;chatter&#8221; may be useful when testing and
debugging memory management, but should not be used otherwise. The
scheduling of garbage collections is not normally of interest even
to programmers, and chatter of this sort may give the illusion
that a program is spending much more time garbage collecting than
is actually the case.</p>
<p>Versions of GNU Emacs prior to 19.31 (May 1996) used to display
the message &#8220;Garbage collecting...&#8221; during a collection. Erik
Naggum commented on this feature:</p>
<blockquote class="last">
<div>I have run some tests at the U of Oslo with about 100
users who generally agreed that Emacs had become faster in
the latest Emacs pretest. All I had done was to remove the
&#8220;Garbage collecting&#8221; message which people perceive as
slowing Emacs down and tell them that it had been sped up.</div></blockquote>
</div>
</div>
<div class="section" id="message-types">
<span id="index-3"></span><h2>11.3. Message types<a class="headerlink" href="#message-types" title="Permalink to this headline"></a></h2>
<dl class="type">
<dt id="mps_message_type_t">
<tt class="descname">mps_message_type_t</tt><a class="headerlink" href="#mps_message_type_t" title="Permalink to this definition"></a></dt>
<dd><p>The type of <a class="reference internal" href="../glossary/m.html#term-message-type"><em class="xref std std-term">message types</em></a>.</p>
<p>There are three message types:</p>
<ol class="arabic simple">
<li><a class="reference internal" href="finalization.html#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></li>
<li><a class="reference internal" href="collection.html#mps_message_type_gc" title="mps_message_type_gc"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_type_gc()</span></tt></a></li>
<li><a class="reference internal" href="collection.html#mps_message_type_gc_start" title="mps_message_type_gc_start"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_type_gc_start()</span></tt></a></li>
</ol>
</dd></dl>
<dl class="function">
<dt id="mps_message_type_disable">
void <tt class="descname">mps_message_type_disable</tt><big>(</big><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_message_type_t" title="mps_message_type_t">mps_message_type_t</a><em>&nbsp;message_type</em><big>)</big><a class="headerlink" href="#mps_message_type_disable" title="Permalink to this definition"></a></dt>
<dd><p>Restore an <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> to the default state whereby
<a class="reference internal" href="../glossary/m.html#term-message"><em class="xref std std-term">messages</em></a> of the specified <a class="reference internal" href="../glossary/m.html#term-message-type"><em class="xref std std-term">message type</em></a>
are not posted, reversing the effect of an earlier call to
<a class="reference internal" href="#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>.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is an arena.</p>
<p><tt class="docutils literal"><span class="pre">message_type</span></tt> is the message type to be disabled.</p>
<p>Any existing messages of the specified type are flushed from the
<a class="reference internal" href="../glossary/m.html#term-message-queue"><em class="xref std std-term">message queue</em></a> of <tt class="docutils literal"><span class="pre">arena</span></tt>.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">It is permitted to call this function when <tt class="docutils literal"><span class="pre">message_type</span></tt> is
already disabled, in which case it has no effect.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_message_type_enable">
void <tt class="descname">mps_message_type_enable</tt><big>(</big><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_message_type_t" title="mps_message_type_t">mps_message_type_t</a><em>&nbsp;message_type</em><big>)</big><a class="headerlink" href="#mps_message_type_enable" title="Permalink to this definition"></a></dt>
<dd><p>Enable an <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> to post <a class="reference internal" href="../glossary/m.html#term-message"><em class="xref std std-term">messages</em></a> of a
specified <a class="reference internal" href="../glossary/m.html#term-message-type"><em class="xref std std-term">message type</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is an arena.</p>
<p><tt class="docutils literal"><span class="pre">message_type</span></tt> is the message type to be disabled.</p>
<p>This function tells the MPS that <tt class="docutils literal"><span class="pre">arena</span></tt> may post messages of
<tt class="docutils literal"><span class="pre">message_type</span></tt> to its <a class="reference internal" href="../glossary/m.html#term-message-queue"><em class="xref std std-term">message queue</em></a>. By default, the MPS
does not generate any messages of any type.</p>
<p>A <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> that enables messages for a message type
must access messages by calling <a class="reference internal" href="#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
discard them by calling <a class="reference internal" href="#mps_message_discard" title="mps_message_discard"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_discard()</span></tt></a>, or the
message queue may consume unbounded resources.</p>
<p>The client program may disable the posting of messages by calling
<a class="reference internal" href="#mps_message_type_disable" title="mps_message_type_disable"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_type_disable()</span></tt></a>.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">It is permitted to call this function when <tt class="docutils literal"><span class="pre">message_type</span></tt> is
already enabled, in which case it has no effect.</p>
</div>
</dd></dl>
</div>
<div class="section" id="message-interface">
<span id="index-4"></span><h2>11.4. Message interface<a class="headerlink" href="#message-interface" title="Permalink to this headline"></a></h2>
<dl class="type">
<dt id="mps_message_t">
<tt class="descname">mps_message_t</tt><a class="headerlink" href="#mps_message_t" title="Permalink to this definition"></a></dt>
<dd><p>The type of a <a class="reference internal" href="../glossary/m.html#term-message"><em class="xref std std-term">message</em></a>.</p>
<p>Messages are <a class="reference internal" href="../glossary/m.html#term-manual-memory-management"><em class="xref std std-term">manually</em></a> managed.
They are created at the instigation of the MPS (but see
<a class="reference internal" href="#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>), and are deleted by the
<a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> by calling <a class="reference internal" href="#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>
<p>An <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> has a <a class="reference internal" href="../glossary/m.html#term-message-queue"><em class="xref std std-term">message queue</em></a> from which messages
can be obtained by calling <a class="reference internal" href="#mps_message_get" title="mps_message_get"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_get()</span></tt></a>.</p>
<p>An <a class="reference internal" href="#mps_message_t" title="mps_message_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_message_t</span></tt></a> is a <a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">reference</em></a> into MPS managed
memory, and can safely be <a class="reference internal" href="../glossary/f.html#term-fix"><em class="xref std std-term">fixed</em></a>.</p>
</dd></dl>
<dl class="function">
<dt id="mps_message_clock">
<a class="reference internal" href="interface.html#mps_clock_t" title="mps_clock_t">mps_clock_t</a> <tt class="descname">mps_message_clock</tt><big>(</big><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_message_t" title="mps_message_t">mps_message_t</a><em>&nbsp;message</em><big>)</big><a class="headerlink" href="#mps_message_clock" title="Permalink to this definition"></a></dt>
<dd><p>Returns the time at which the MPS posted a <a class="reference internal" href="../glossary/m.html#term-message"><em class="xref std std-term">message</em></a>.</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="#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.</p>
<p>If <tt class="docutils literal"><span class="pre">message</span></tt> belongs to one of the following supported message,
return the time at which the MPS posted the message:</p>
<ul class="simple">
<li><a class="reference internal" href="collection.html#mps_message_type_gc" title="mps_message_type_gc"><tt class="xref c c-type docutils literal"><span class="pre">mps_message_type_gc</span></tt></a>;</li>
<li><a class="reference internal" href="collection.html#mps_message_type_gc_start" title="mps_message_type_gc_start"><tt class="xref c c-type docutils literal"><span class="pre">mps_message_type_gc_start</span></tt></a>.</li>
</ul>
<p>For other message types, the value returned is always zero.</p>
<p>Messages are asynchronous: they are posted by the MPS, wait on a
queue, and are later collected by the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a>. Each
message (of the supported message types) records the time that it
was posted, and this is what <a class="reference internal" href="#mps_message_clock" title="mps_message_clock"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_clock()</span></tt></a> returns.</p>
<p>The time returned is the <a class="reference internal" href="interface.html#mps_clock_t" title="mps_clock_t"><tt class="xref c c-func docutils literal"><span class="pre">mps_clock_t()</span></tt></a> value returned by
the <a class="reference internal" href="../glossary/p.html#term-plinth"><em class="xref std std-term">plinth</em></a> function <a class="reference internal" href="plinth.html#mps_clock" title="mps_clock"><tt class="xref c c-func docutils literal"><span class="pre">mps_clock()</span></tt></a> at the time the
message was posted. You can subtract one clock value from another
to get the time interval between the posting of two messages.</p>
</dd></dl>
<dl class="function">
<dt id="mps_message_discard">
void <tt class="descname">mps_message_discard</tt><big>(</big><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_message_t" title="mps_message_t">mps_message_t</a><em>&nbsp;message</em><big>)</big><a class="headerlink" href="#mps_message_discard" title="Permalink to this definition"></a></dt>
<dd><p>Indicate to the MPS that the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> has no further
use for a <a class="reference internal" href="../glossary/m.html#term-message"><em class="xref std std-term">message</em></a> and the MPS can now reclaim any storage
associated with the message.</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 the message. After this call, <tt class="docutils literal"><span class="pre">message</span></tt> is invalid
and should not be passed as an argument to any message functions.</p>
<p>Messages are essentially <a class="reference internal" href="../glossary/m.html#term-manual-memory-management"><em class="xref std std-term">manually</em></a> managed. This function allows the MPS to reclaim
storage associated with messages. If the client does not discard
messages then the resources used may grow without bound.</p>
<p>As well as consuming resources, messages may have other effects
that require them to be tidied by calling this function. In
particular finalization messages refer to a <a class="reference internal" href="../glossary/f.html#term-finalized-block"><em class="xref std std-term">finalized
block</em></a>, and prevent the object from being reclaimed (subject to
the usual <a class="reference internal" href="../glossary/g.html#term-garbage-collection"><em class="xref std std-term">garbage collection</em></a> liveness analysis). A
finalized block cannot be reclaimed until all its finalization
messages have been discarded. See
<a class="reference internal" href="finalization.html#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>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="finalization.html#topic-finalization"><em>Finalization</em></a>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_message_type">
<a class="reference internal" href="#mps_message_type_t" title="mps_message_type_t">mps_message_type_t</a> <tt class="descname">mps_message_type</tt><big>(</big><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_message_t" title="mps_message_t">mps_message_t</a><em>&nbsp;message</em><big>)</big><a class="headerlink" href="#mps_message_type" 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 a <a class="reference internal" href="../glossary/m.html#term-message"><em class="xref std std-term">message</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena that 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="#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.</p>
</dd></dl>
</div>
<div class="section" id="message-queue-interface">
<span id="index-5"></span><h2>11.5. Message queue interface<a class="headerlink" href="#message-queue-interface" title="Permalink to this headline"></a></h2>
<dl class="function">
<dt id="mps_message_get">
<a class="reference internal" href="interface.html#mps_bool_t" title="mps_bool_t">mps_bool_t</a> <tt class="descname">mps_message_get</tt><big>(</big><a class="reference internal" href="#mps_message_t" title="mps_message_t">mps_message_t</a><em>&nbsp;*message_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_message_type_t" title="mps_message_type_t">mps_message_type_t</a><em>&nbsp;message_type</em><big>)</big><a class="headerlink" href="#mps_message_get" title="Permalink to this definition"></a></dt>
<dd><p>Get a <a class="reference internal" href="../glossary/m.html#term-message"><em class="xref std std-term">message</em></a> of a specified type from the <a class="reference internal" href="../glossary/m.html#term-message-queue"><em class="xref std std-term">message
queue</em></a> for 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">message_o</span></tt> points to a location that will hold the address of the
message if the function succeeds.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena.</p>
<p><tt class="docutils literal"><span class="pre">message_type</span></tt> is the type of message to return.</p>
<p>If there is at least one message of the specified type on the
message queue of the specified arena, then this function removes
one such message from the queue, stores a pointer to the message
in the location pointed to by <tt class="docutils literal"><span class="pre">message_o</span></tt>, and returns true.
Otherwise it returns false.</p>
</dd></dl>
<dl class="function">
<dt id="mps_message_poll">
<a class="reference internal" href="interface.html#mps_bool_t" title="mps_bool_t">mps_bool_t</a> <tt class="descname">mps_message_poll</tt><big>(</big><a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_message_poll" title="Permalink to this definition"></a></dt>
<dd><p>Determine whether there are currently any <a class="reference internal" href="../glossary/m.html#term-message"><em class="xref std std-term">messages</em></a> on a <a class="reference internal" href="../glossary/m.html#term-message-queue"><em class="xref std std-term">message queue</em></a> for 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">arena</span></tt> is the arena whose message queue will be polled.</p>
<p>Returns true if there is at least one message on the message queue
for <tt class="docutils literal"><span class="pre">arena</span></tt>, or false if the message queue is empty.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">If you are interested in a particular type of message, it is
usually simpler to call <a class="reference internal" href="#mps_message_get" title="mps_message_get"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_get()</span></tt></a>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_message_queue_type">
<a class="reference internal" href="interface.html#mps_bool_t" title="mps_bool_t">mps_bool_t</a> <tt class="descname">mps_message_queue_type</tt><big>(</big><a class="reference internal" href="#mps_message_type_t" title="mps_message_type_t">mps_message_type_t</a><em>&nbsp;*message_type_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_message_queue_type" title="Permalink to this definition"></a></dt>
<dd><p>Determine whether there are currently any <a class="reference internal" href="../glossary/m.html#term-message"><em class="xref std std-term">messages</em></a> on a <a class="reference internal" href="../glossary/m.html#term-message-queue"><em class="xref std std-term">message queue</em></a> for an <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a>, and
return the <a class="reference internal" href="../glossary/m.html#term-message-type"><em class="xref std std-term">message type</em></a> of the first message, if any.</p>
<p><tt class="docutils literal"><span class="pre">message_type_o</span></tt> points to a location that will hold the message
type of the first message on the queue, if any.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena whose message queue will be polled.</p>
<p>If there is at least one message on the message queue of <tt class="docutils literal"><span class="pre">arena</span></tt>,
then this function returns true, and also writes the message type
of the first message on the queue into the location pointed to by
<tt class="docutils literal"><span class="pre">message_type_o</span></tt>. If there are no messages on the message queue,
it returns false.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">If you are interested in a particular type of message, it is
usually simpler to call <a class="reference internal" href="#mps_message_get" title="mps_message_get"><tt class="xref c c-func docutils literal"><span class="pre">mps_message_get()</span></tt></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="#">11. Messages</a><ul>
<li><a class="reference internal" href="#finalization-messages">11.1. Finalization messages</a></li>
<li><a class="reference internal" href="#example-interactive-chatter">11.2. Example: interactive chatter</a></li>
<li><a class="reference internal" href="#message-types">11.3. Message types</a></li>
<li><a class="reference internal" href="#message-interface">11.4. Message interface</a></li>
<li><a class="reference internal" href="#message-queue-interface">11.5. Message queue interface</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="collection.html"
title="previous chapter">10. Garbage collection</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="finalization.html"
title="next chapter">12. Finalization</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="finalization.html" title="12. Finalization"
>next</a> |</li>
<li class="right" >
<a href="collection.html" title="10. Garbage collection"
>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> 2012, 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