mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-01-04 02:51:31 -08:00
Code Issues Projects Releases Wiki Activity
emacs/mps/manual/html/topic/arena.html
Gareth Rees 2ed2ff1893 Updated manual html 
Copied from Perforce
 Change: 181750
 ServerID: perforce.ravenbrook.com
2013-05-13 21:04:49 +01:00

904 lines
No EOL
81 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>4. Arenas &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="5. Pools" href="pool.html" />
<link rel="prev" title="3. Error handing" href="error.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="pool.html" title="5. Pools"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="error.html" title="3. Error handing"
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="arenas">
<span id="topic-arena"></span><span id="index-0"></span><h1>4. Arenas<a class="headerlink" href="#arenas" title="Permalink to this headline"></a></h1>
<p>An arena is an object that encapsulates the state of the Memory Pool
System, and tells it where to get the memory it manages. You typically
start a session with the MPS by creating an arena with
<a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> and end the session by destroying it with
<a class="reference internal" href="#mps_arena_destroy" title="mps_arena_destroy"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_destroy()</span></tt></a>. The only function you might need to call
before making an arena is <a class="reference internal" href="telemetry.html#mps_telemetry_control" title="mps_telemetry_control"><tt class="xref c c-func docutils literal"><span class="pre">mps_telemetry_control()</span></tt></a>.</p>
<p>Before destroying an arena, you must first destroy all objects and
data in it, as usual for abstract data types in the MPS. If you can&#8217;t
destroy the arena properly (for example, because your program has
crashed and you are at the debugger prompt), you can still call
<a class="reference internal" href="telemetry.html#mps_telemetry_flush" title="mps_telemetry_flush"><tt class="xref c c-func docutils literal"><span class="pre">mps_telemetry_flush()</span></tt></a> explicitly.</p>
<p>Other types of objects in the MPS are created &#8220;in the arena&#8221;. They are
part of the world within the arena, and may interact and affect each
other.</p>
<div class="admonition-note admonition" id="index-1">
<p class="first admonition-title">Note</p>
<p>The MPS allows creation of multiple arenas, but you would only do
this in unusual circumstances. It might be useful to have two
active arenas and to try different things out in them, or you
might be in the process of integrating two pieces of software that
each independently uses the MPS.</p>
<p class="last">Arenas do not normally interact, but they compete with each other
for resources, and references from one arena to another are not
traced, though you <em>can</em> declare <a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">roots</em></a> pointing
from one arena to another. It is not efficient to have multiple
arenas containing <a class="reference internal" href="../glossary/a.html#term-automatic-memory-management"><em class="xref std std-term">automatically managed</em></a> <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pools</em></a>: if you find yourself in this
situation it&#8217;s best to find a way to move all the automatically
managed pools to one arena.</p>
</div>
<p>The open source MPS comes with two classes of arena,
<a class="reference internal" href="#topic-arena-client"><em>Client arenas</em></a> and <a class="reference internal" href="#topic-arena-vm"><em>Virtual memory arenas</em></a>. These differ in
the way that they acquire the memory to be managed.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">The MPS is designed to be extensible with new arena classes. If
you need features that are not provided by any of the open source
arena classes, <a class="reference internal" href="../contact.html#contact"><em>contact us</em></a>.</p>
</div>
<dl class="type">
<dt id="mps_arena_t">
<tt class="descname">mps_arena_t</tt><a class="headerlink" href="#mps_arena_t" title="Permalink to this definition"></a></dt>
<dd><p>The type of <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arenas</em></a>.</p>
<p>An arena is responsible for requesting <a class="reference internal" href="../glossary/m.html#term-memory-3"><em class="xref std std-term">memory<sup>(3)</sup></em></a> from
the operating system, making it available to <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pools</em></a>,
and for <a class="reference internal" href="../glossary/g.html#term-garbage-collection"><em class="xref std std-term">garbage collection</em></a>.</p>
</dd></dl>
<dl class="type">
<dt id="mps_arena_class_t">
<tt class="descname">mps_arena_class_t</tt><a class="headerlink" href="#mps_arena_class_t" title="Permalink to this definition"></a></dt>
<dd><p>The type of <a class="reference internal" href="../glossary/a.html#term-arena-class"><em class="xref std std-term">arena classes</em></a>.</p>
</dd></dl>
<dl class="function">
<dt id="mps_arena_create_k">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_arena_create_k</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;*arena_o</em>, <a class="reference internal" href="#mps_arena_class_t" title="mps_arena_class_t">mps_arena_class_t</a><em>&nbsp;arena_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_arena_create_k" title="Permalink to this definition"></a></dt>
<dd><p>Create 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_o</span></tt> points to a location that will hold a pointer to the new
arena.</p>
<p><tt class="docutils literal"><span class="pre">arena_class</span></tt> is the <a class="reference internal" href="../glossary/a.html#term-arena-class"><em class="xref std std-term">arena class</em></a>.</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 arena
class. See the documentation for the arena 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 arena 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 arena persists until it is destroyed by calling
<a class="reference internal" href="#mps_arena_destroy" title="mps_arena_destroy"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_destroy()</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="mps_arena_create">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_arena_create</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;*arena_o</em>, <a class="reference internal" href="#mps_arena_class_t" title="mps_arena_class_t">mps_arena_class_t</a><em>&nbsp;arena_class</em>, ...<big>)</big><a class="headerlink" href="#mps_arena_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_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_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_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_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_arena_create_v">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_arena_create_v</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;*arena_o</em>, <a class="reference internal" href="#mps_arena_class_t" title="mps_arena_class_t">mps_arena_class_t</a><em>&nbsp;arena_class</em>, va_list<em>&nbsp;args</em><big>)</big><a class="headerlink" href="#mps_arena_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_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_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_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_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_arena_destroy">
void <tt class="descname">mps_arena_destroy</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_arena_destroy" title="Permalink to this definition"></a></dt>
<dd><p>Destroy 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 to destroy.</p>
<p>This function checks the consistency of the arena, flushes the
<a class="reference internal" href="../glossary/t.html#term-telemetry-stream"><em class="xref std std-term">telemetry stream</em></a> and destroys the arena&#8217;s internal control
structures. Additionally, <a class="reference internal" href="../glossary/v.html#term-virtual-memory-arena"><em class="xref std std-term">virtual memory arenas</em></a> return
their reserved address space to the operating system if possible.</p>
<p>It is an error to destroy an arena without first destroying all
<a class="reference internal" href="../glossary/g.html#term-generation-chain"><em class="xref std std-term">generation chains</em></a>, <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object formats</em></a>, <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pools</em></a>
and <a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">roots</em></a> created in the arena, and deregistering all
<a class="reference internal" href="../glossary/t.html#term-thread"><em class="xref std std-term">threads</em></a> registered with the arena.</p>
</dd></dl>
<div class="section" id="client-arenas">
<span id="topic-arena-client"></span><span id="index-2"></span><h2>4.1. Client arenas<a class="headerlink" href="#client-arenas" title="Permalink to this headline"></a></h2>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include &quot;mpsacl.h&quot;</span>
</pre></div>
</div>
<dl class="function">
<dt id="mps_arena_class_cl">
<a class="reference internal" href="#mps_arena_class_t" title="mps_arena_class_t">mps_arena_class_t</a> <tt class="descname">mps_arena_class_cl</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_arena_class_cl" title="Permalink to this definition"></a></dt>
<dd><p>Return the <a class="reference internal" href="../glossary/a.html#term-arena-class"><em class="xref std std-term">arena class</em></a> for a <a class="reference internal" href="../glossary/c.html#term-client-arena"><em class="xref std std-term">client arena</em></a>.</p>
<p>A client arena gets its managed memory from the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client
program</em></a>. This memory chunk is passed when the arena is created.</p>
<p>When creating a client arena, <a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> requires two
<a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword arguments</em></a>:</p>
<ul class="simple">
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_ARENA_CL_BASE</span></tt> (type <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_addr_t</span></tt></a>) is
the <a class="reference internal" href="../glossary/a.html#term-address"><em class="xref std std-term">address</em></a> of the chunk of memory that will be managed
by the arena.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_ARENA_SIZE</span></tt> (type <tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>) is its
size.</li>
</ul>
<p>For example:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">MPS_ARGS_BEGIN</span><span class="p">(</span><span class="n">args</span><span class="p">)</span> <span class="p">{</span>
<span class="n">MPS_ARGS_ADD</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">MPS_KEY_ARENA_CL_BASE</span><span class="p">,</span> <span class="n">base</span><span class="p">);</span>
<span class="n">MPS_ARGS_ADD</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">MPS_KEY_ARENA_SIZE</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="n">MPS_ARGS_DONE</span><span class="p">(</span><span class="n">args</span><span class="p">);</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_arena_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">arena</span><span class="p">,</span> <span class="n">mps_arena_class_cl</span><span class="p">(),</span> <span class="n">args</span><span class="p">);</span>
<span class="p">}</span> <span class="n">MPS_ARGS_END</span><span class="p">(</span><span class="n">args</span><span class="p">);</span>
</pre></div>
</div>
<p>If the chunk is too small to hold the internal arena structures,
<a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> returns <a class="reference internal" href="error.html#MPS_RES_MEMORY" title="MPS_RES_MEMORY"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_MEMORY</span></tt></a>. In
this case, you need to use a (much) larger chunk.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p>You don&#8217;t have to provide all the memory up front: you can
call <a class="reference internal" href="#mps_arena_extend" title="mps_arena_extend"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_extend()</span></tt></a> later on.</p>
<p class="last">Client arenas have no mechanism for returning unused memory.</p>
</div>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="#mps_arena_create" title="mps_arena_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create()</span></tt></a>, pass the size and base
address like this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_arena_create</span><span class="p">(</span><span class="n">mps_arena_t</span> <span class="o">*</span><span class="n">arena_o</span><span class="p">,</span>
<span class="n">mps_arena_class_t</span> <span class="n">mps_arena_class_cl</span><span class="p">,</span>
<span class="kt">size_t</span> <span class="n">size</span><span class="p">,</span> <span class="n">mps_addr_t</span> <span class="n">base</span><span class="p">)</span>
</pre></div>
</div>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_arena_extend">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_arena_extend</tt><big>(</big><a class="reference internal" href="#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;base</em>, size_t<em>&nbsp;size</em><big>)</big><a class="headerlink" href="#mps_arena_extend" title="Permalink to this definition"></a></dt>
<dd><p>Extend a <a class="reference internal" href="../glossary/c.html#term-client-arena"><em class="xref std std-term">client arena</em></a> with another block of memory.</p>
<p><tt class="docutils literal"><span class="pre">base</span></tt> is the <a class="reference internal" href="../glossary/a.html#term-address"><em class="xref std std-term">address</em></a> of the block of memory that will be
managed by the arena.</p>
<p><tt class="docutils literal"><span class="pre">size</span></tt> is its <a class="reference internal" href="../glossary/s.html#term-size"><em class="xref std std-term">size</em></a>.</p>
<p>Return <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 it fails.</p>
</dd></dl>
</div>
<div class="section" id="virtual-memory-arenas">
<span id="topic-arena-vm"></span><span id="index-3"></span><h2>4.2. Virtual memory arenas<a class="headerlink" href="#virtual-memory-arenas" title="Permalink to this headline"></a></h2>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include &quot;mpsavm.h&quot;</span>
</pre></div>
</div>
<dl class="function">
<dt id="mps_arena_class_vm">
<a class="reference internal" href="#mps_arena_class_t" title="mps_arena_class_t">mps_arena_class_t</a> <tt class="descname">mps_arena_class_vm</tt><big>(</big>void<big>)</big><a class="headerlink" href="#mps_arena_class_vm" title="Permalink to this definition"></a></dt>
<dd><p>Return the <a class="reference internal" href="../glossary/a.html#term-arena-class"><em class="xref std std-term">arena class</em></a> for a <a class="reference internal" href="../glossary/v.html#term-virtual-memory-arena"><em class="xref std std-term">virtual memory arena</em></a>.</p>
<p>A virtual memory arena uses the operating system&#8217;s <a class="reference internal" href="../glossary/v.html#term-virtual-memory"><em class="xref std std-term">virtual
memory</em></a> interface to allocate memory. The chief consequence of
this is that the arena can manage many more virtual addresses than
it needs to commit memory to. This gives it flexibility as to
where to place <a class="reference internal" href="../glossary/b.html#term-block"><em class="xref std std-term">blocks</em></a>, which reduces
<a class="reference internal" href="../glossary/f.html#term-fragmentation"><em class="xref std std-term">fragmentation</em></a> and helps make <a class="reference internal" href="../glossary/g.html#term-garbage-collection"><em class="xref std std-term">garbage collection</em></a>
more efficient.</p>
<p>When creating a virtual memory arena, <a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a>
requires one <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword argument</em></a>:</p>
<ul>
<li><p class="first"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_ARENA_SIZE</span></tt> (type <tt class="xref c c-type docutils literal"><span class="pre">size_t</span></tt>). is the
initial amount of virtual address space, in <a class="reference internal" href="../glossary/b.html#term-byte-1"><em class="xref std std-term">bytes<sup>(1)</sup></em></a>,
that the arena will reserve (this space is initially reserved so
that the arena can subsequently use it without interference from
other parts of the program, but most of it is not committed, so
it doesn&#8217;t require any RAM or backing store). The arena may
allocate more virtual address space beyond this initial
reservation as and when it deems it necessary. The MPS is most
efficient if you reserve an address space that is several times
larger than your peak memory usage.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">The MPS asks for more address space if it runs out, but the
more times it has to extend its address space, the less
efficient garbage collection will become.</p>
</div>
</li>
</ul>
<p>An optional <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword argument</em></a> may be passed, but is
only used on the Windows operating system:</p>
<ul>
<li><p class="first"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_VMW3_TOP_DOWN</span></tt> (type <a class="reference internal" href="interface.html#mps_bool_t" title="mps_bool_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_bool_t</span></tt></a>). If
true, the arena will allocate address space starting at the
highest possible address and working downwards through memory.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">This causes the arena to pass the <tt class="docutils literal"><span class="pre">MEM_TOP_DOWN</span></tt> flag to
<a class="reference external" href="http://msdn.microsoft.com/en-us/library/windows/desktop/aa366887%28v=vs.85%29.aspx">VirtualAlloc</a>.</p>
</div>
</li>
</ul>
<p>If the MPS fails to reserve adequate address space to place the
arena in, <a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> returns
<a class="reference internal" href="error.html#MPS_RES_RESOURCE" title="MPS_RES_RESOURCE"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_RESOURCE</span></tt></a>. Possibly this means that other parts
of the program are reserving too much virtual memory.</p>
<p>If the MPS fails to allocate memory for the internal arena
structures, <a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> returns
<a class="reference internal" href="error.html#MPS_RES_MEMORY" title="MPS_RES_MEMORY"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_RES_MEMORY</span></tt></a>. Either <tt class="docutils literal"><span class="pre">size</span></tt> was far too small or
the operating system refused to provide enough memory.</p>
<p>For example:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="n">MPS_ARGS_BEGIN</span><span class="p">(</span><span class="n">args</span><span class="p">)</span> <span class="p">{</span>
<span class="n">MPS_ARGS_ADD</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">MPS_KEY_ARENA_SIZE</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
<span class="n">MPS_ARGS_DONE</span><span class="p">(</span><span class="n">args</span><span class="p">);</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">mps_arena_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">arena</span><span class="p">,</span> <span class="n">mps_arena_class_cl</span><span class="p">(),</span> <span class="n">args</span><span class="p">);</span>
<span class="p">}</span> <span class="n">MPS_ARGS_END</span><span class="p">(</span><span class="n">args</span><span class="p">);</span>
</pre></div>
</div>
<div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p>starting with version 1.112.</p>
<p>When using <a class="reference internal" href="#mps_arena_create" title="mps_arena_create"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create()</span></tt></a>, pass the size like
this:</p>
<div class="last highlight-c"><div class="highlight"><pre><span class="n">mps_res_t</span> <span class="n">mps_arena_create</span><span class="p">(</span><span class="n">mps_arena_t</span> <span class="o">*</span><span class="n">arena_o</span><span class="p">,</span>
<span class="n">mps_arena_class_t</span> <span class="n">arena_class_vm</span><span class="p">(),</span>
<span class="kt">size_t</span> <span class="n">size</span><span class="p">)</span>
</pre></div>
</div>
</div>
</dd></dl>
</div>
<div class="section" id="arena-properties">
<span id="index-4"></span><h2>4.3. Arena properties<a class="headerlink" href="#arena-properties" title="Permalink to this headline"></a></h2>
<dl class="function">
<dt id="mps_collections">
<a class="reference internal" href="interface.html#mps_word_t" title="mps_word_t">mps_word_t</a> <tt class="descname">mps_collections</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_collections" title="Permalink to this definition"></a></dt>
<dd><p>Return the number of <a class="reference internal" href="../glossary/f.html#term-flip"><em class="xref std std-term">flips</em></a> that have taken place in an
<a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> since it was created.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena.</p>
</dd></dl>
<dl class="function">
<dt id="mps_arena_commit_limit">
size_t <tt class="descname">mps_arena_commit_limit</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_arena_commit_limit" title="Permalink to this definition"></a></dt>
<dd><p>Return the current <a class="reference internal" href="../glossary/c.html#term-commit-limit"><em class="xref std std-term">commit limit</em></a> for
an arena.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena to return the commit limit for.</p>
<p>Returns the commit limit in <a class="reference internal" href="../glossary/b.html#term-byte-1"><em class="xref std std-term">bytes<sup>(1)</sup></em></a>. The commit limit
controls how much memory the MPS can obtain from the operating
system, and can be changed by calling
<a class="reference internal" href="#mps_arena_commit_limit_set" title="mps_arena_commit_limit_set"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_commit_limit_set()</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="mps_arena_commit_limit_set">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_arena_commit_limit_set</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, size_t<em>&nbsp;limit</em><big>)</big><a class="headerlink" href="#mps_arena_commit_limit_set" title="Permalink to this definition"></a></dt>
<dd><p>Change the <a class="reference internal" href="../glossary/c.html#term-commit-limit"><em class="xref std std-term">commit limit</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 to change the commit limit for.</p>
<p><tt class="docutils literal"><span class="pre">limit</span></tt> is the new commit limit in <a class="reference internal" href="../glossary/b.html#term-byte-1"><em class="xref std std-term">bytes<sup>(1)</sup></em></a>.</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>If successful, the commit limit for <tt class="docutils literal"><span class="pre">arena</span></tt> is set to <tt class="docutils literal"><span class="pre">limit</span></tt>. The
commit limit controls how much memory the MPS will obtain from the
operating system. The commit limit cannot be set to a value that
is lower than the number of bytes that the MPS is using. If an
attempt is made to set the commit limit to a value greater than or
equal to that returned by <a class="reference internal" href="#mps_arena_committed" title="mps_arena_committed"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_committed()</span></tt></a> then it
will succeed. If an attempt is made to set the commit limit to a
value less than that returned by <a class="reference internal" href="#mps_arena_committed" title="mps_arena_committed"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_committed()</span></tt></a>
then it will succeed only if the amount committed by the MPS can
be reduced by reducing the amount of spare committed memory; in
such a case the spare committed memory will be reduced
appropriately and the attempt will succeed.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="#mps_arena_commit_limit_set" title="mps_arena_commit_limit_set"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_commit_limit_set()</span></tt></a> puts a limit on all
memory committed by the MPS. The <a class="reference internal" href="../glossary/s.html#term-spare-committed-memory"><em class="xref std std-term">spare committed
memory</em></a> can be limited separately with
<a class="reference internal" href="#mps_arena_spare_commit_limit_set" title="mps_arena_spare_commit_limit_set"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_spare_commit_limit_set()</span></tt></a>. Note that &#8220;spare
committed&#8221; memory is subject to both limits; there cannot be
more spare committed memory than the spare commit limit, and
there can&#8217;t be so much spare committed memory that there is
more committed memory than the commit limit.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_arena_committed">
size_t <tt class="descname">mps_arena_committed</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_arena_committed" title="Permalink to this definition"></a></dt>
<dd><p>Return the total <a class="reference internal" href="../glossary/m.html#term-mapped"><em class="xref std std-term">committed</em></a> memory 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.</p>
<p>Returns the total amount of memory that has been committed to RAM
by the MPS, in <a class="reference internal" href="../glossary/b.html#term-byte-1"><em class="xref std std-term">bytes<sup>(1)</sup></em></a>.</p>
<p>The committed memory is generally larger than the sum of the sizes
of the allocated <a class="reference internal" href="../glossary/b.html#term-block"><em class="xref std std-term">blocks</em></a>. The reasons for this are:</p>
<ul class="simple">
<li>some memory is used internally by the MPS to manage its own data
structures and to record information about allocated blocks
(such as free lists, page tables, colour tables, statistics, and
so on);</li>
<li>operating systems (and hardware) typically restrict programs to
requesting and releasing memory with a certain granularity (for
example, <a class="reference internal" href="../glossary/p.html#term-page"><em class="xref std std-term">pages</em></a>), so extra memory is committed
when this rounding is necessary;</li>
<li>there might also be <a class="reference internal" href="../glossary/s.html#term-spare-committed-memory"><em class="xref std std-term">spare committed memory</em></a>: see
<a class="reference internal" href="#mps_arena_spare_committed" title="mps_arena_spare_committed"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_spare_committed()</span></tt></a>.</li>
</ul>
<p>The amount of committed memory is a good measure of how much
virtual memory resource (&#8220;swap space&#8221;) the MPS is using from the
operating system.</p>
<p>The function <a class="reference internal" href="#mps_arena_committed" title="mps_arena_committed"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_committed()</span></tt></a> may be called whatever
state the the arena is in (<a class="reference internal" href="../glossary/u.html#term-unclamped-state"><em class="xref std std-term">unclamped</em></a>,
<a class="reference internal" href="../glossary/c.html#term-clamped-state"><em class="xref std std-term">clamped</em></a>, or <a class="reference internal" href="../glossary/p.html#term-parked-state"><em class="xref std std-term">parked</em></a>). If it is called when the arena is in the unclamped state
then the value may change after this function returns. A possible
use might be to call it just after <a class="reference internal" href="#mps_arena_collect" title="mps_arena_collect"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_collect()</span></tt></a> to
(over-)estimate the size of the heap.</p>
<p>If you want to know how much memory the MPS is using then you&#8217;re
probably interested in the value <tt class="docutils literal"><span class="pre">mps_arena_committed()</span> <span class="pre">-</span>
<span class="pre">mps_arena_spare_committed()</span></tt>.</p>
<p>The amount of committed memory can be limited with the function
<a class="reference internal" href="#mps_arena_commit_limit" title="mps_arena_commit_limit"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_commit_limit()</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="mps_arena_reserved">
size_t <tt class="descname">mps_arena_reserved</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_arena_reserved" title="Permalink to this definition"></a></dt>
<dd><p>Return the total <a class="reference internal" href="../glossary/a.html#term-address-space"><em class="xref std std-term">address space</em></a> reserved by an
<a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a>, in <a class="reference internal" href="../glossary/b.html#term-byte-1"><em class="xref std std-term">bytes<sup>(1)</sup></em></a>.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena.</p>
<p>For a <a class="reference internal" href="../glossary/v.html#term-virtual-memory-arena"><em class="xref std std-term">virtual memory arena</em></a>, this is the total address space
reserved via the operating system&#8217;s virtual memory interface.</p>
<p>For a <a class="reference internal" href="../glossary/c.html#term-client-arena"><em class="xref std std-term">client arena</em></a>, this is the sum of the usable portions
of the chunks of memory passed to the arena by 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="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> and
<a class="reference internal" href="#mps_arena_extend" title="mps_arena_extend"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_extend()</span></tt></a>.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">For a client arena, the reserved address may be lower than the
sum of the <tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_ARENA_SIZE</span></tt> keyword argument
passed to <a class="reference internal" href="#mps_arena_create_k" title="mps_arena_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_create_k()</span></tt></a> and the <tt class="docutils literal"><span class="pre">size</span></tt>
arguments passed to <a class="reference internal" href="#mps_arena_extend" title="mps_arena_extend"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_extend()</span></tt></a>, because the
arena may be unable to use the whole of each chunk for reasons
of alignment.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_arena_spare_commit_limit">
size_t <tt class="descname">mps_arena_spare_commit_limit</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_arena_spare_commit_limit" title="Permalink to this definition"></a></dt>
<dd><p>Return the current <a class="reference internal" href="../glossary/s.html#term-spare-commit-limit"><em class="xref std std-term">spare commit limit</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 to return the spare commit limit for.</p>
<p>Returns the spare commit limit in <a class="reference internal" href="../glossary/b.html#term-byte-1"><em class="xref std std-term">bytes<sup>(1)</sup></em></a>. The spare
commit limit can be changed by calling
<a class="reference internal" href="#mps_arena_spare_commit_limit_set" title="mps_arena_spare_commit_limit_set"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_spare_commit_limit_set()</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="mps_arena_spare_commit_limit_set">
void <tt class="descname">mps_arena_spare_commit_limit_set</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, size_t<em>&nbsp;limit</em><big>)</big><a class="headerlink" href="#mps_arena_spare_commit_limit_set" title="Permalink to this definition"></a></dt>
<dd><p>Change the <a class="reference internal" href="../glossary/s.html#term-spare-commit-limit"><em class="xref std std-term">spare commit limit</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 to change the spare commit limit for.</p>
<p><tt class="docutils literal"><span class="pre">limit</span></tt> is the new spare commit limit in <a class="reference internal" href="../glossary/b.html#term-byte-1"><em class="xref std std-term">bytes<sup>(1)</sup></em></a>.</p>
<p>The spare commit limit is the maximum amount of <a class="reference internal" href="../glossary/s.html#term-spare-committed-memory"><em class="xref std std-term">spare
committed memory</em></a> the MPS is allowed to have. Setting it to a
value lower than the current amount of spare committed memory
causes spare committed memory to be uncommitted so as to bring the
value under the limit. In particular, setting it to 0 will mean
that the MPS will have no spare committed memory.</p>
<p>Non-virtual-memory arena classes (for example, a <a class="reference internal" href="../glossary/c.html#term-client-arena"><em class="xref std std-term">client
arena</em></a>) do not have spare committed memory. For these arenas, this
function functions sets a value but has no other effect.</p>
<p>Initially the spare commit limit is a configuration-dependent
value. The value of the limit can be retrieved by the function
<a class="reference internal" href="#mps_arena_spare_commit_limit" title="mps_arena_spare_commit_limit"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_spare_commit_limit()</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="mps_arena_spare_committed">
size_t <tt class="descname">mps_arena_spare_committed</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_arena_spare_committed" title="Permalink to this definition"></a></dt>
<dd><p>Return the total <a class="reference internal" href="../glossary/s.html#term-spare-committed-memory"><em class="xref std std-term">spare committed memory</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.</p>
<p>Returns the number of bytes of spare committed memory.</p>
<p>Spare committed memory is memory which the arena is managing as
free memory (not in use by any pool and not otherwise in use for
internal reasons) but which remains committed (mapped to RAM by
the operating system). It is used by the arena to (attempt to)
avoid calling the operating system to repeatedly map and unmap
areas of <a class="reference internal" href="../glossary/v.html#term-virtual-memory"><em class="xref std std-term">virtual memory</em></a> as the amount of memory in use
goes up and down. Spare committed memory is counted as committed
memory by <a class="reference internal" href="#mps_arena_committed" title="mps_arena_committed"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_committed()</span></tt></a> and is restricted by
<a class="reference internal" href="#mps_arena_commit_limit" title="mps_arena_commit_limit"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_commit_limit()</span></tt></a>.</p>
<p>The amount of &#8220;spare committed&#8221; memory can be limited by calling
<a class="reference internal" href="#mps_arena_spare_commit_limit_set" title="mps_arena_spare_commit_limit_set"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_spare_commit_limit_set()</span></tt></a>, and the value of that
limit can be retrieved with
<a class="reference internal" href="#mps_arena_spare_commit_limit" title="mps_arena_spare_commit_limit"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_spare_commit_limit()</span></tt></a>. This is analogous to the
functions for limiting the amount of <a class="reference internal" href="../glossary/m.html#term-mapped"><em class="xref std std-term">committed</em></a>
memory.</p>
</dd></dl>
</div>
<div class="section" id="arena-states">
<span id="index-5"></span><h2>4.4. Arena states<a class="headerlink" href="#arena-states" title="Permalink to this headline"></a></h2>
<p>An arena is always in one of three states.</p>
<ol class="arabic">
<li><p id="index-6">In the <em>unclamped state</em>, garbage collection may take place,
objects may move in memory, references may be updated,
<a class="reference internal" href="../glossary/l.html#term-location-dependency"><em class="xref std std-term">location dependencies</em></a> may become stale, virtual memory may
be requested from or return to the operating system, and other
kinds of background activity may occur. This is the normal state.</p>
</li>
<li><p id="index-7">In the <em>clamped state</em>, objects do not move in memory, references
do not change, the staleness of <a class="reference internal" href="../glossary/l.html#term-location-dependency"><em class="xref std std-term">location dependencies</em></a> does
not change, and memory occupied by <a class="reference internal" href="../glossary/u.html#term-unreachable"><em class="xref std std-term">unreachable</em></a> objects is
not recycled.</p>
<p>However, a <a class="reference internal" href="../glossary/g.html#term-garbage-collection"><em class="xref std std-term">garbage collection</em></a> may be in progress and
incremental collection may still occur, but it will not be visible
to the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> and no new collections will begin.</p>
</li>
<li><p id="index-8">The <em>parked state</em> is the same as the clamped state, with the
additional constraint that no garbage collections are in progress.</p>
</li>
</ol>
<p>The clamped and parked states are used for introspection and
debugging. If you are examining the contents of the heap, you don&#8217;t
want data moving under your feet. So for example, if your program is
stopped in GDB you might type:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="p">(</span><span class="n">gdb</span><span class="p">)</span> <span class="n">print</span> <span class="n">mps_arena_clamp</span><span class="p">(</span><span class="n">arena</span><span class="p">)</span>
</pre></div>
</div>
<p>before inspecting memory, and:</p>
<div class="highlight-c"><div class="highlight"><pre><span class="p">(</span><span class="n">gdb</span><span class="p">)</span> <span class="n">print</span> <span class="n">mps_arena_release</span><span class="p">(</span><span class="n">arena</span><span class="p">)</span>
</pre></div>
</div>
<p>afterward.</p>
<p>The results of introspection functions like
<a class="reference internal" href="#mps_arena_has_addr" title="mps_arena_has_addr"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_has_addr()</span></tt></a> only remain valid while the arena remains
in the parked state, and functions like <a class="reference internal" href="root.html#mps_arena_roots_walk" title="mps_arena_roots_walk"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_roots_walk()</span></tt></a>
can only be called in this state.</p>
<dl class="function">
<dt id="mps_arena_clamp">
void <tt class="descname">mps_arena_clamp</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_arena_clamp" title="Permalink to this definition"></a></dt>
<dd><p>Put an <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> into the <a class="reference internal" href="../glossary/c.html#term-clamped-state"><em class="xref std std-term">clamped state</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena to clamp.</p>
<p>In the clamped state, no object motion will occur and the
staleness of <a class="reference internal" href="../glossary/l.html#term-location-dependency"><em class="xref std std-term">location dependencies</em></a> will not change. All
references to objects loaded while the arena is clamped will keep
the same binary representation until after it is released by
calling <a class="reference internal" href="#mps_arena_release" title="mps_arena_release"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_release()</span></tt></a>.</p>
<p>In a clamped arena, incremental collection may still occur, but it
will not be visible to the mutator and no new collections will
begin. Space used by unreachable objects will not be recycled
until the arena is unclamped.</p>
</dd></dl>
<dl class="function">
<dt id="mps_arena_park">
void <tt class="descname">mps_arena_park</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_arena_park" title="Permalink to this definition"></a></dt>
<dd><p>Put an <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> into the <a class="reference internal" href="../glossary/p.html#term-parked-state"><em class="xref std std-term">parked state</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena to park.</p>
<p>While an arena is parked, no object motion will occur and the
staleness of <a class="reference internal" href="../glossary/l.html#term-location-dependency"><em class="xref std std-term">location dependencies</em></a> will not change. All
references to objects loaded while the arena is parked will keep
the same binary representation until after it is released.</p>
<p>Any current collection is run to completion before the arena is
parked, and no new collections will start. When an arena is in the
parked state, it is necessarily not in the middle of a collection.</p>
</dd></dl>
<dl class="function">
<dt id="mps_arena_release">
void <tt class="descname">mps_arena_release</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_arena_release" title="Permalink to this definition"></a></dt>
<dd><p>Puts an arena into the <a class="reference internal" href="../glossary/u.html#term-unclamped-state"><em class="xref std std-term">unclamped state</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena to unclamp.</p>
<p>While an arena is unclamped, <a class="reference internal" href="../glossary/g.html#term-garbage-collection"><em class="xref std std-term">garbage collection</em></a>, object
motion, and other background activity can take place.</p>
</dd></dl>
</div>
<div class="section" id="running-garbage-collections">
<span id="index-9"></span><h2>4.5. Running garbage collections<a class="headerlink" href="#running-garbage-collections" title="Permalink to this headline"></a></h2>
<p>The Memory Pool System&#8217;s garbage collector runs <a class="reference internal" href="../glossary/a.html#term-asynchronous-garbage-collector"><em class="xref std std-term">asynchronously</em></a> and <a class="reference internal" href="../glossary/i.html#term-incremental-garbage-collection"><em class="xref std std-term">incrementally</em></a>. This means that it is not normally
necessary to tell it when to start garbage collections, or to wait
until it has finished collecting. (But if your program has idle time
that could be productively spent by the MPS, see
<a class="reference internal" href="#topic-arena-idle"><em>Using idle time for collection</em></a> below.)</p>
<p>However, during development and testing it is useful to be able to
request that MPS run a full <a class="reference internal" href="../glossary/c.html#term-collection-cycle"><em class="xref std std-term">collection cycle</em></a>. For example, you
might run frequent collections in an attempt to detect bugs in your
allocation and scanning code.</p>
<dl class="function">
<dt id="mps_arena_collect">
void <tt class="descname">mps_arena_collect</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_arena_collect" title="Permalink to this definition"></a></dt>
<dd><p>Collect an arena and put it into the <a class="reference internal" href="../glossary/p.html#term-parked-state"><em class="xref std std-term">parked state</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena to collect.</p>
<p>The collector attempts to recycle as many unreachable objects as
possible and reduce the size of the arena as much as possible
(though in some cases it may increase because it becomes more
fragmented). Note that the collector may not be able to recycle
some objects (such as those near the destination of ambiguous
references) even though they are not reachable.</p>
<p>If you do not want the arena to remain in the parked state, you
must explicitly call <a class="reference internal" href="#mps_arena_release" title="mps_arena_release"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_release()</span></tt></a> afterwards.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">It is not normally necessary to call this function: in the
<a class="reference internal" href="../glossary/u.html#term-unclamped-state"><em class="xref std std-term">unclamped state</em></a>, collections start automatically.
However, it may be useful during development and debugging:
the more frequently the collector runs, the sooner and more
reliably errors are discovered. See <a class="reference internal" href="../guide/debug.html#guide-debug-advice"><em>General debugging advice</em></a>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_arena_start_collect">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_arena_start_collect</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_arena_start_collect" title="Permalink to this definition"></a></dt>
<dd><p>Request an <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> to start a full <a class="reference internal" href="../glossary/c.html#term-collection-cycle"><em class="xref std std-term">collection cycle</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena.</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 a collection is started, 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 puts <tt class="docutils literal"><span class="pre">arena</span></tt> into the <a class="reference internal" href="../glossary/u.html#term-unclamped-state"><em class="xref std std-term">unclamped state</em></a> and
requests that it start a full collection cycle. The call to
<a class="reference internal" href="#mps_arena_start_collect" title="mps_arena_start_collect"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_start_collect()</span></tt></a> returns quickly, leaving the
collection to proceed incrementally (as for a collection that is
scheduled automatically).</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">Contrast with <a class="reference internal" href="#mps_arena_collect" title="mps_arena_collect"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_collect()</span></tt></a>, which does not
return until the collection has completed.</p>
</div>
</dd></dl>
</div>
<div class="section" id="using-idle-time-for-collection">
<span id="topic-arena-idle"></span><span id="index-10"></span><h2>4.6. Using idle time for collection<a class="headerlink" href="#using-idle-time-for-collection" title="Permalink to this headline"></a></h2>
<p>Some types of program have &#8220;idle time&#8221; in which they are waiting for
an external event such as user input or network activity. The MPS
provides a function, <a class="reference internal" href="#mps_arena_step" title="mps_arena_step"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_step()</span></tt></a>, for making use of idle
time to make memory management progress.</p>
<p>Here&#8217;s an example illustrating the use of this function in a program&#8217;s
event loop. When the program is idle (there are no client actions to
perform), it requests that the MPS spend up to 10 milliseconds on
incremental work, by calling <tt class="docutils literal"><span class="pre">mps_arena_step(arena,</span> <span class="pre">0.010,</span>
<span class="pre">0.0)</span></tt>. When this returns false to indicate that there is no more work
to do, the program blocks on the client for two seconds: if this times
out, it predicts that the user will remain idle for at least a further
second, so it calls <tt class="docutils literal"><span class="pre">mps_arena_step(arena,</span> <span class="pre">0.010,</span> <span class="pre">100.0)</span></tt> to tell
that it&#8217;s a good time to start a collection taking up to 10&nbsp;ms × 100
= 1&nbsp;second, but not to pause for more than 10&nbsp;ms.</p>
<p>The program remains responsive: the MPS doesn&#8217;t take control for more
than a few milliseconds at a time (at most 10). But at the same time,
major collection work can get done at times when the program would
otherwise be idle. Of course the numbers here are only for
illustration and should be chosen based on the requirements of the
application.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">for</span> <span class="p">(;;)</span> <span class="p">{</span> <span class="cm">/* event loop */</span>
<span class="k">for</span> <span class="p">(;;)</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="n">client_is_waiting</span><span class="p">())</span> <span class="p">{</span>
<span class="n">perform_client_action</span><span class="p">();</span>
<span class="p">}</span> <span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">mps_arena_step</span><span class="p">(</span><span class="n">arena</span><span class="p">,</span> <span class="mf">0.010</span><span class="p">,</span> <span class="mf">0.0</span><span class="p">))</span> <span class="p">{</span>
<span class="cm">/* no incremental MPS work remaining */</span>
<span class="k">break</span><span class="p">;</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">block_on_client_with_timeout</span><span class="p">(</span><span class="mf">2.0</span><span class="p">))</span> <span class="p">{</span>
<span class="cm">/* Perhaps the user has gone for a cup of coffee? Allow the</span>
<span class="cm"> * MPS to start a big piece of work, but don&#39;t actually pause</span>
<span class="cm"> * for more than 10 ms. */</span>
<span class="n">mps_arena_step</span><span class="p">(</span><span class="n">arena</span><span class="p">,</span> <span class="mf">0.010</span><span class="p">,</span> <span class="mf">100.0</span><span class="p">);</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<dl class="function">
<dt id="mps_arena_step">
<a class="reference internal" href="interface.html#mps_bool_t" title="mps_bool_t">mps_bool_t</a> <tt class="descname">mps_arena_step</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, double<em>&nbsp;interval</em>, double<em>&nbsp;multiplier</em><big>)</big><a class="headerlink" href="#mps_arena_step" title="Permalink to this definition"></a></dt>
<dd><p>Request an <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> to do some work during a period where the
<a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> is idle.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena.</p>
<p><tt class="docutils literal"><span class="pre">interval</span></tt> is the time, in seconds, the MPS is permitted to
take. It must not be negative, but may be <tt class="docutils literal"><span class="pre">0.0</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">multiplier</span></tt> is the number of further similar calls that the
client program expects to make during this idle period.</p>
<p>Returns true if there was work for the MPS to do in <tt class="docutils literal"><span class="pre">arena</span></tt>
(regardless of whether or not it did any) or false if there was
nothing to do.</p>
<p><a class="reference internal" href="#mps_arena_step" title="mps_arena_step"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_step()</span></tt></a> allows the client program to make use of
idle time to do some garbage collection, for example when it is
waiting for interactive input. The MPS makes every effort to
return from this function within <tt class="docutils literal"><span class="pre">interval</span></tt> seconds, but cannot
guarantee to do so, as it may need to call your own scanning
code. It uses <tt class="docutils literal"><span class="pre">multiplier</span></tt> to decide whether to commence
long-duration operations that consume CPU (such as a full
collection): it will only start such an operation if it is
expected to be completed within <tt class="docutils literal"><span class="pre">multiplier</span> <span class="pre">*</span> <span class="pre">interval</span></tt> seconds.</p>
<p>If the arena was in the <a class="reference internal" href="../glossary/p.html#term-parked-state"><em class="xref std std-term">parked state</em></a> or the <a class="reference internal" href="../glossary/c.html#term-clamped-state"><em class="xref std std-term">clamped
state</em></a> before <a class="reference internal" href="#mps_arena_step" title="mps_arena_step"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_step()</span></tt></a> was called, it is in the
clamped state afterwards. It it was in the <a class="reference internal" href="../glossary/u.html#term-unclamped-state"><em class="xref std std-term">unclamped
state</em></a>, it remains there.</p>
</dd></dl>
</div>
<div class="section" id="arena-introspection">
<span id="index-11"></span><h2>4.7. Arena introspection<a class="headerlink" href="#arena-introspection" title="Permalink to this headline"></a></h2>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p>Introspection functions covered in other chapters are:</p>
<ul class="last simple">
<li><a class="reference internal" href="format.html#mps_addr_fmt" title="mps_addr_fmt"><tt class="xref c c-func docutils literal"><span class="pre">mps_addr_fmt()</span></tt></a>: determine the <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> to
which an address belongs;</li>
<li><a class="reference internal" href="format.html#mps_arena_formatted_objects_walk" title="mps_arena_formatted_objects_walk"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_formatted_objects_walk()</span></tt></a>: visit all
<a class="reference internal" href="../glossary/f.html#term-formatted-object"><em class="xref std std-term">formatted objects</em></a> in an arena;</li>
<li><a class="reference internal" href="root.html#mps_arena_roots_walk" title="mps_arena_roots_walk"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_roots_walk()</span></tt></a>: visit all references in
<a class="reference internal" href="../glossary/r.html#term-root"><em class="xref std std-term">roots</em></a> registered with an arena; and</li>
<li><a class="reference internal" href="pool.html#mps_addr_pool" title="mps_addr_pool"><tt class="xref c c-func docutils literal"><span class="pre">mps_addr_pool()</span></tt></a>: 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.</li>
</ul>
</div>
<dl class="function">
<dt id="mps_arena_has_addr">
<a class="reference internal" href="interface.html#mps_bool_t" title="mps_bool_t">mps_bool_t</a> <tt class="descname">mps_arena_has_addr</tt><big>(</big><a class="reference internal" href="#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_arena_has_addr" title="Permalink to this definition"></a></dt>
<dd><p>Test whether an <a class="reference internal" href="../glossary/a.html#term-address"><em class="xref std std-term">address</em></a> is managed by 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 an arena.</p>
<p><tt class="docutils literal"><span class="pre">addr</span></tt> is an address.</p>
<p>Returns true if <tt class="docutils literal"><span class="pre">addr</span></tt> is managed by <tt class="docutils literal"><span class="pre">arena</span></tt>; false otherwise.</p>
<p>An arena manages a portion of <a class="reference internal" href="../glossary/a.html#term-address-space"><em class="xref std std-term">address space</em></a>. No two arenas
overlap, so for any particular address this function will return
true for at most one arena.</p>
<p>In general, not all addresses are managed by any arena. This is
what allows the MPS to cooperate with other memory managers,
shared object loaders, memory mapped file input/ouput, and so on:
it does not steal the whole address space.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</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 example, a
<a class="reference internal" href="../glossary/g.html#term-garbage-collection"><em class="xref std std-term">garbage collection</em></a> may occur, the address in question
may become free, the arena may choose to unmap the address and
return storage to the operating system). 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 class="section" id="protection-interface">
<span id="index-12"></span><h2>4.8. Protection interface<a class="headerlink" href="#protection-interface" title="Permalink to this headline"></a></h2>
<dl class="function">
<dt id="mps_arena_expose">
void <tt class="descname">mps_arena_expose</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_arena_expose" title="Permalink to this definition"></a></dt>
<dd><div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p class="last">starting with version 1.111.</p>
</div>
<p>Ensure that the MPS is not protecting any <a class="reference internal" href="../glossary/p.html#term-page"><em class="xref std std-term">page</em></a> in the
<a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> with a <a class="reference internal" href="../glossary/r.html#term-read-barrier"><em class="xref std std-term">read barrier</em></a> or <a class="reference internal" href="../glossary/w.html#term-write-barrier"><em class="xref std std-term">write
barrier</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">mps_arena</span></tt> is the arena to expose.</p>
<p>This is expected to only be useful for debugging. The arena is
left in the <a class="reference internal" href="../glossary/c.html#term-clamped-state"><em class="xref std std-term">clamped state</em></a>.</p>
<p>Since barriers are used during a collection, calling this function
has the same effect as calling <a class="reference internal" href="#mps_arena_park" title="mps_arena_park"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_park()</span></tt></a>: all
collections are run to completion, and the arena is clamped so
that no new collections begin. The MPS also uses barriers to
maintain <a class="reference internal" href="../glossary/r.html#term-remembered-set"><em class="xref std std-term">remembered sets</em></a>, so calling this
function will effectively destroy the remembered sets and any
optimization gains from them.</p>
<p>Calling this function is time-consuming: any active collections
will be run to completion; and the next collection will have to
recompute all the remembered sets by scanning the entire arena.</p>
<p>The recomputation of the remembered sets can be avoided by calling
<a class="reference internal" href="#mps_arena_unsafe_expose_remember_protection" title="mps_arena_unsafe_expose_remember_protection"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_unsafe_expose_remember_protection()</span></tt></a> instead of
<a class="reference internal" href="#mps_arena_expose" title="mps_arena_expose"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_expose()</span></tt></a>, and by calling
<a class="reference internal" href="#mps_arena_unsafe_restore_protection" title="mps_arena_unsafe_restore_protection"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_unsafe_restore_protection()</span></tt></a> before calling
<a class="reference internal" href="#mps_arena_release" title="mps_arena_release"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_release()</span></tt></a>. Those functions have unsafe aspects
and place restrictions on what the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> can do
(basically no exposed data can be changed).</p>
</dd></dl>
<dl class="function">
<dt id="mps_arena_unsafe_expose_remember_protection">
void <tt class="descname">mps_arena_unsafe_expose_remember_protection</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_arena_unsafe_expose_remember_protection" title="Permalink to this definition"></a></dt>
<dd><div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p class="last">starting with version 1.111.</p>
</div>
<p>Ensure that the MPS is not protecting any <a class="reference internal" href="../glossary/p.html#term-page"><em class="xref std std-term">page</em></a> in the
<a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a> with a <a class="reference internal" href="../glossary/r.html#term-read-barrier"><em class="xref std std-term">read barrier</em></a> or <a class="reference internal" href="../glossary/w.html#term-write-barrier"><em class="xref std std-term">write
barrier</em></a>. In addition, request the MPS to remember some parts of its
internal state so that they can be restored later.</p>
<p><tt class="docutils literal"><span class="pre">mps_arena</span></tt> is the arena to expose.</p>
<p>This function is the same as <a class="reference internal" href="#mps_arena_expose" title="mps_arena_expose"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_expose()</span></tt></a>, but
additionally causes the MPS to remember its protection state. The
remembered protection state can optionally be restored later by
calling the <a class="reference internal" href="#mps_arena_unsafe_restore_protection" title="mps_arena_unsafe_restore_protection"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_unsafe_restore_protection()</span></tt></a> function.
This is an optimization that avoids the MPS having to recompute
all the remembered sets by scanning the entire arena.</p>
<p>However, restoring the remembered protections is only safe if the
contents of the exposed pages have not been changed; therefore
this function should only be used if you do not intend to change
the pages, and the remembered protection must only be restored if
the pages have not been changed.</p>
<p>The MPS will only remember the protection state if resources
(memory) are available. If memory is low then only some or
possibly none of the protection state will be remembered, with a
corresponding necessity to recompute it later. The MPS provides no
mechanism for the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> to determine whether the
MPS has in fact remembered the protection state.</p>
<p>The remembered protection state, if any, is discarded after
calling <a class="reference internal" href="#mps_arena_unsafe_restore_protection" title="mps_arena_unsafe_restore_protection"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_unsafe_restore_protection()</span></tt></a>, or as soon
as the arena leaves the <a class="reference internal" href="../glossary/c.html#term-clamped-state"><em class="xref std std-term">clamped state</em></a> by calling
<a class="reference internal" href="#mps_arena_release" title="mps_arena_release"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_release()</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="mps_arena_unsafe_restore_protection">
void <tt class="descname">mps_arena_unsafe_restore_protection</tt><big>(</big><a class="reference internal" href="#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em><big>)</big><a class="headerlink" href="#mps_arena_unsafe_restore_protection" title="Permalink to this definition"></a></dt>
<dd><div class="admonition-deprecated admonition">
<p class="first admonition-title">Deprecated</p>
<p class="last">starting with version 1.111.</p>
</div>
<p>Restore the remembered protection state 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">mps_arena</span></tt> is the arena to restore the protection state for.</p>
<p>This function restores the protection state that the MPS has
remembered when the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client program</em></a> called
<a class="reference internal" href="#mps_arena_unsafe_expose_remember_protection" title="mps_arena_unsafe_expose_remember_protection"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_unsafe_expose_remember_protection()</span></tt></a>. The purpose
of remembering and restoring the protection state is to avoid the
need for the MPS to recompute all the <a class="reference internal" href="../glossary/r.html#term-remembered-set"><em class="xref std std-term">remembered sets</em></a> by scanning the entire arena, that occurs when
<a class="reference internal" href="#mps_arena_expose" title="mps_arena_expose"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_expose()</span></tt></a> is used, and which causes the next
<a class="reference internal" href="../glossary/g.html#term-garbage-collection"><em class="xref std std-term">garbage collection</em></a> to be slow.</p>
<p>The client program must not change the exposed data between the
call to <a class="reference internal" href="#mps_arena_unsafe_expose_remember_protection" title="mps_arena_unsafe_expose_remember_protection"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_unsafe_expose_remember_protection()</span></tt></a> and
<a class="reference internal" href="#mps_arena_unsafe_restore_protection" title="mps_arena_unsafe_restore_protection"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_unsafe_restore_protection()</span></tt></a>. If the client
program has changed the exposed data then
<a class="reference internal" href="#mps_arena_unsafe_restore_protection" title="mps_arena_unsafe_restore_protection"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_unsafe_restore_protection()</span></tt></a> must not be called:
in this case simply call <a class="reference internal" href="#mps_arena_release" title="mps_arena_release"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_release()</span></tt></a>.</p>
<p>Calling this function does not release the arena from the clamped
state: <a class="reference internal" href="#mps_arena_release" title="mps_arena_release"><tt class="xref c c-func docutils literal"><span class="pre">mps_arena_release()</span></tt></a> must be called to continue
normal collections.</p>
<p>Calling this function causes the MPS to forget the remember
protection state; as a consequence the same remembered state
cannot be restored more than once.</p>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/logo.png" alt="Logo"/>
</a></p>
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">4. Arenas</a><ul>
<li><a class="reference internal" href="#client-arenas">4.1. Client arenas</a></li>
<li><a class="reference internal" href="#virtual-memory-arenas">4.2. Virtual memory arenas</a></li>
<li><a class="reference internal" href="#arena-properties">4.3. Arena properties</a></li>
<li><a class="reference internal" href="#arena-states">4.4. Arena states</a></li>
<li><a class="reference internal" href="#running-garbage-collections">4.5. Running garbage collections</a></li>
<li><a class="reference internal" href="#using-idle-time-for-collection">4.6. Using idle time for collection</a></li>
<li><a class="reference internal" href="#arena-introspection">4.7. Arena introspection</a></li>
<li><a class="reference internal" href="#protection-interface">4.8. Protection interface</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="error.html"
title="previous chapter">3. Error handing</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="pool.html"
title="next chapter">5. Pools</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="pool.html" title="5. Pools"
>next</a> |</li>
<li class="right" >
<a href="error.html" title="3. Error handing"
>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