mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-03-15 03:11:54 -07:00
Code Issues Projects Releases Wiki Activity
emacs/mps/manual/html/topic/format.html
Richard Brooksby e940ea3732 Updated manual html 
Copied from Perforce
 Change: 182591
 ServerID: perforce.ravenbrook.com
2013-06-06 20:59:14 +01:00

689 lines
No EOL
62 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>7. Object formats &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="8. Scanning" href="scanning.html" />
<link rel="prev" title="6. Allocation" href="allocation.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="scanning.html" title="8. Scanning"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="allocation.html" title="6. Allocation"
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="object-formats">
<span id="topic-format"></span><span id="index-0"></span><h1>7. Object formats<a class="headerlink" href="#object-formats" title="Permalink to this headline"></a></h1>
<p>The need for some means of describing objects in the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client
program</em></a> comes from <a class="reference internal" href="../glossary/t.html#term-trace"><em class="xref std std-term">tracing</em></a> and <a class="reference internal" href="../glossary/m.html#term-moving-memory-manager"><em class="xref std std-term">moving</em></a>. During tracing, when an object is <a class="reference internal" href="../glossary/s.html#term-scan"><em class="xref std std-term">scanned</em></a>, all the <a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">references</em></a> in the object must be
identified so that the objects they point to can be scanned in their
turn. When an object has moved, references to that object must be
identified so that they can be updated to point to the new location of
the object.</p>
<p>In general, only the client program can say which fields in an object
are references, and only the client program knows how references are
represented (for example, are they tagged?). <em>Object formats</em> provide
the means by which the client program communicates this information to
the MPS.</p>
<p>An object format is a collection of <a class="reference internal" href="../glossary/f.html#term-format-method"><em class="xref std std-term">format methods</em></a> and other
(usually scalar) values which together describe programatically the
layout of objects belonging to the format. Format methods include the
<a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip method</em></a> (which calculates an object&#8217;s size), the
<a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan method</em></a> (which <a class="reference internal" href="../glossary/f.html#term-fix"><em class="xref std std-term">fixes</em></a> references in the
object), and the <a class="reference internal" href="../glossary/f.html#term-forward-method"><em class="xref std std-term">forward method</em></a> (which replaces an object that
has moved with a <a class="reference internal" href="../glossary/f.html#term-forwarding-object"><em class="xref std std-term">forwarding object</em></a>).</p>
<p>Not every <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool class</em></a> supports <a class="reference internal" href="../glossary/f.html#term-formatted-object"><em class="xref std std-term">formatted objects</em></a>.</p>
<div class="section" id="interface">
<span id="index-1"></span><h2>7.1. Interface<a class="headerlink" href="#interface" title="Permalink to this headline"></a></h2>
<dl class="type">
<dt id="mps_fmt_t">
<tt class="descname">mps_fmt_t</tt><a class="headerlink" href="#mps_fmt_t" title="Permalink to this definition"></a></dt>
<dd><p>The type of an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>.</p>
</dd></dl>
<dl class="function">
<dt id="mps_fmt_create_k">
void <tt class="descname">mps_fmt_create_k</tt><big>(</big><a class="reference internal" href="#mps_fmt_t" title="mps_fmt_t">mps_fmt_t</a><em>&nbsp;*mps_fmt_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="keyword.html#mps_arg_s" title="mps_arg_s">mps_arg_s</a><em>&nbsp;args[]</em><big>)</big><a class="headerlink" href="#mps_fmt_create_k" title="Permalink to this definition"></a></dt>
<dd><p>Create an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">fmt_o</span></tt> points to a location that will hold the address of the new
object format.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena in which to create the format.</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> describing the format. Each
<a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool class</em></a> requires a particular subset of these keyword
arguments: see the documentation for that pool class.</p>
<ul class="simple">
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_FMT_ALIGN</span></tt> (type <a class="reference internal" href="interface.html#mps_align_t" title="mps_align_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_align_t</span></tt></a>,
default <a class="reference internal" href="platform.html#MPS_PF_ALIGN" title="MPS_PF_ALIGN"><tt class="xref c c-macro docutils literal"><span class="pre">MPS_PF_ALIGN</span></tt></a>) is an integer value specifying
the alignment of objects allocated with this format. It should
be large enough to satisfy the alignment requirements of any
field in the objects, and it must not be larger than the pool
alignment.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_FMT_HEADER_SIZE</span></tt> (type <tt class="xref c c-type docutils literal"><span class="pre">mps_size_t</span></tt>,
default 0) is an integer value specifying the header size for
objects with <a class="reference internal" href="../glossary/i.html#term-in-band-header"><em class="xref std std-term">in-band headers</em></a>. See
<a class="reference internal" href="#topic-format-headers"><em>In-band headers</em></a> below.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_FMT_SCAN</span></tt> (type <a class="reference internal" href="#mps_fmt_scan_t" title="mps_fmt_scan_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_scan_t</span></tt></a>) is a
<a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan method</em></a> that identifies references within objects
belonging to this format. See <a class="reference internal" href="#mps_fmt_scan_t" title="mps_fmt_scan_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_scan_t</span></tt></a>.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_FMT_SKIP</span></tt> (type <a class="reference internal" href="#mps_fmt_skip_t" title="mps_fmt_skip_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_skip_t</span></tt></a>) is a
<a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip method</em></a> that skips over objects belonging to this
format. See <a class="reference internal" href="#mps_fmt_skip_t" title="mps_fmt_skip_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_skip_t</span></tt></a>.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_FMT_FWD</span></tt> (type <a class="reference internal" href="#mps_fmt_fwd_t" title="mps_fmt_fwd_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_fwd_t</span></tt></a>) is a
<a class="reference internal" href="../glossary/f.html#term-forward-method"><em class="xref std std-term">forward method</em></a> that stores relocation information for an
object belonging to this format that has moved. See
<a class="reference internal" href="#mps_fmt_fwd_t" title="mps_fmt_fwd_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_fwd_t</span></tt></a>.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_FMT_ISFWD</span></tt> (type <a class="reference internal" href="#mps_fmt_isfwd_t" title="mps_fmt_isfwd_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_isfwd_t</span></tt></a>) is
a <a class="reference internal" href="../glossary/i.html#term-is-forwarded-method"><em class="xref std std-term">is-forwarded method</em></a> that determines if an object
belonging to this format has been moved. See
<a class="reference internal" href="#mps_fmt_isfwd_t" title="mps_fmt_isfwd_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_isfwd_t</span></tt></a>.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_FMT_PAD</span></tt> (type <a class="reference internal" href="#mps_fmt_pad_t" title="mps_fmt_pad_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_pad_t</span></tt></a>) is a
<a class="reference internal" href="../glossary/p.html#term-padding-method"><em class="xref std std-term">padding method</em></a> that creates <a class="reference internal" href="../glossary/p.html#term-padding-object"><em class="xref std std-term">padding objects</em></a>
belonging to this format. See <a class="reference internal" href="#mps_fmt_pad_t" title="mps_fmt_pad_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_pad_t</span></tt></a>.</li>
<li><tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_FMT_CLASS</span></tt> (type <a class="reference internal" href="#mps_fmt_class_t" title="mps_fmt_class_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_class_t</span></tt></a>) is
a method that returns an address that is related to the class or
type of the object, for inclusion in the <a class="reference internal" href="../glossary/t.html#term-telemetry-stream"><em class="xref std std-term">telemetry
stream</em></a> for some events relating to the object. See
<a class="reference internal" href="#mps_fmt_class_t" title="mps_fmt_class_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_class_t</span></tt></a>.</li>
</ul>
<p><a class="reference internal" href="#mps_fmt_create_k" title="mps_fmt_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_fmt_create_k()</span></tt></a> 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. The MPS may exhaust some resource in the course of
<a class="reference internal" href="#mps_fmt_create_k" title="mps_fmt_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_fmt_create_k()</span></tt></a> and will return an appropriate
<a class="reference internal" href="../glossary/r.html#term-result-code"><em class="xref std std-term">result code</em></a> if so.</p>
<p>The object format pointed to by <tt class="docutils literal"><span class="pre">fmt_o</span></tt> persists until it is
destroyed by calling <a class="reference internal" href="#mps_fmt_destroy" title="mps_fmt_destroy"><tt class="xref c c-func docutils literal"><span class="pre">mps_fmt_destroy()</span></tt></a>.</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_FMT_ALIGN</span><span class="p">,</span> <span class="n">ALIGNMENT</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_FMT_SCAN</span><span class="p">,</span> <span class="n">obj_scan</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_FMT_SKIP</span><span class="p">,</span> <span class="n">obj_skip</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_FMT_FWD</span><span class="p">,</span> <span class="n">obj_fwd</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_FMT_ISFWD</span><span class="p">,</span> <span class="n">obj_isfwd</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_FMT_PAD</span><span class="p">,</span> <span class="n">obj_pad</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_fmt_create_k</span><span class="p">(</span><span class="o">&amp;</span><span class="n">obj_fmt</span><span class="p">,</span> <span class="n">arena</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>
<span class="k">if</span> <span class="p">(</span><span class="n">res</span> <span class="o">!=</span> <span class="n">MPS_RES_OK</span><span class="p">)</span> <span class="n">error</span><span class="p">(</span><span class="s">&quot;Couldn&#39;t create obj format&quot;</span><span class="p">);</span>
</pre></div>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_fmt_destroy">
void <tt class="descname">mps_fmt_destroy</tt><big>(</big><a class="reference internal" href="#mps_fmt_t" title="mps_fmt_t">mps_fmt_t</a><em>&nbsp;fmt</em><big>)</big><a class="headerlink" href="#mps_fmt_destroy" title="Permalink to this definition"></a></dt>
<dd><p>Destroy an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">fmt</span></tt> is the object format to destroy.</p>
<p>It is an error to destroy an object format if there exists a
<a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a> using the format. The pool must be destroyed first.</p>
</dd></dl>
</div>
<div class="section" id="in-band-headers">
<span id="topic-format-headers"></span><span id="index-2"></span><h2>7.2. In-band headers<a class="headerlink" href="#in-band-headers" title="Permalink to this headline"></a></h2>
<p>There are use cases in which it is convenient for the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client
program&#8217;s</em></a> pointers to point some distance into the
memory <a class="reference internal" href="../glossary/b.html#term-block"><em class="xref std std-term">block</em></a> containing the object. This typically happens
when the objects have a common <a class="reference internal" href="../glossary/i.html#term-in-band-header"><em class="xref std std-term">in-band header</em></a> used for memory
management or class system purposes, but this situation also arises
when the low bits of a pointer are used for a tag. The MPS does not
care what the reason is, only about the offset of the pointer in
relation to the memory block.</p>
<p>If you have one of these use cases, you should pass the
<tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_FMT_HEADER_SIZE</span></tt> <a class="reference internal" href="../glossary/k.html#term-keyword-argument"><em class="xref std std-term">keyword argument</em></a> to
<a class="reference internal" href="#mps_fmt_create_k" title="mps_fmt_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_fmt_create_k()</span></tt></a>, specifying the size of the header: that
is, the offset of a client pointer from the base of the memory block.</p>
<p>There are some cautions to be observed when using in-band headers:</p>
<ol class="arabic">
<li><p class="first">The format methods (other than the <a class="reference internal" href="../glossary/p.html#term-padding-method"><em class="xref std std-term">padding method</em></a>) receive
<em>client pointers</em> (that is, pointers past the header) but all other
MPS functions expect to receive and return <em>base pointers</em> (that
is, pointers to the base of the block where the header is stored).</p>
<p>In particular, <a class="reference internal" href="allocation.html#mps_reserve" title="mps_reserve"><tt class="xref c c-func docutils literal"><span class="pre">mps_reserve()</span></tt></a> and <a class="reference internal" href="allocation.html#mps_alloc" title="mps_alloc"><tt class="xref c c-func docutils literal"><span class="pre">mps_alloc()</span></tt></a> always
hand out base pointers, and <a class="reference internal" href="allocation.html#mps_free" title="mps_free"><tt class="xref c c-func docutils literal"><span class="pre">mps_free()</span></tt></a> expects to receive
one.</p>
</li>
<li><p class="first">Formatted objects must be longer than the header. In other words,
objects consisting of only a header are not supported.</p>
</li>
<li><p class="first">Even if the header size is larger than or equal to
<a class="reference internal" href="../glossary/a.html#term-alignment"><em class="xref std std-term">alignment</em></a>, the <a class="reference internal" href="../glossary/p.html#term-padding-method"><em class="xref std std-term">padding method</em></a> must still be able to
create <a class="reference internal" href="../glossary/p.html#term-padding-object"><em class="xref std std-term">padding objects</em></a> down to the alignment size.</p>
</li>
<li><p class="first">Not all <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool classes</em></a> support objects with in-band headers.
See the documentation for the pool class.</p>
</li>
</ol>
</div>
<div class="section" id="cautions">
<span id="topic-format-cautions"></span><span id="index-3"></span><h2>7.3. Cautions<a class="headerlink" href="#cautions" title="Permalink to this headline"></a></h2>
<ol class="arabic">
<li><p class="first">The MPS guarantees that format methods have exclusive access to the
object for the duration of the call. This guarantee may entail
suspending arbitrary threads. The methods that manipulate the
object must not perform any sort of inter-thread locking or
communication.</p>
</li>
<li><p class="first">The MPS may call format methods in the context of an exception
handler or a signal handler. For example, the following sequence of
events is common:</p>
<ol class="loweralpha simple">
<li>the MPS places a <a class="reference internal" href="../glossary/r.html#term-read-barrier"><em class="xref std std-term">read barrier</em></a> on a block of memory;</li>
<li>the client program attempts to read from this block;</li>
<li>the hardware raises a <a class="reference internal" href="../glossary/p.html#term-protection-fault"><em class="xref std std-term">protection fault</em></a>;</li>
<li>the MPS signal handler is called;</li>
<li>the MPS ensures that the contents of the block are correct and
consistent: this may involve inspection of formatted objects in
the block (or indeed, elsewhere), and so</li>
<li>the MPS calls format methods.</li>
</ol>
<p>Therefore, the format methods must be able to be run at any time,
including asynchronously or in parallel with the rest of the
program.</p>
</li>
<li><p class="first">Format methods must be re-entrant.</p>
</li>
<li><p class="first">Format methods must not:</p>
<ol class="loweralpha simple">
<li>call library code;</li>
<li>perform a non-local exit (for example, by calling <tt class="docutils literal"><span class="pre">longjmp</span></tt>);</li>
<li>call any functions in the MPS other than the fix functions
(<a class="reference internal" href="scanning.html#mps_fix" title="mps_fix"><tt class="xref c c-func docutils literal"><span class="pre">mps_fix()</span></tt></a>, <a class="reference internal" href="scanning.html#MPS_FIX1" title="MPS_FIX1"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX1()</span></tt></a>, <a class="reference internal" href="scanning.html#MPS_FIX12" title="MPS_FIX12"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX12()</span></tt></a>, and
<a class="reference internal" href="scanning.html#MPS_FIX2" title="MPS_FIX2"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX2()</span></tt></a>).</li>
</ol>
<p>It&#8217;s permissible to call other functions in the client program, but
see <a class="reference internal" href="scanning.html#MPS_FIX_CALL" title="MPS_FIX_CALL"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX_CALL()</span></tt></a> for a restriction on passing the
<a class="reference internal" href="../glossary/s.html#term-scan-state"><em class="xref std std-term">scan state</em></a>.</p>
</li>
<li><p class="first">Subject to the above constraints, format methods can freely access:</p>
<ol class="loweralpha simple">
<li>memory inside the object or block that they have been asked to
look at;</li>
<li>memory managed by the MPS that is in pools that do not protect
their contents;</li>
<li>memory not managed by the MPS;</li>
</ol>
<p>They must not access other memory managed by the MPS.</p>
</li>
</ol>
</div>
<div class="section" id="format-methods">
<span id="index-4"></span><h2>7.4. Format methods<a class="headerlink" href="#format-methods" title="Permalink to this headline"></a></h2>
<dl class="type">
<dt id="mps_fmt_class_t">
<a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a> <tt class="descname">(*mps_fmt_class_t)</tt><big>(</big><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_fmt_class_t" title="Permalink to this definition"></a></dt>
<dd><p>The type of the class method of an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">addr</span></tt> is the address of the object whose class is of interest.</p>
<p>Returns an address that is related to the class or type of the
object, or a null pointer if this is not possible.</p>
<p>It is recommended that a null pointer be returned for
<a class="reference internal" href="../glossary/p.html#term-padding-object"><em class="xref std std-term">padding objects</em></a> and <a class="reference internal" href="../glossary/f.html#term-forwarding-object"><em class="xref std std-term">forwarding objects</em></a>.</p>
</dd></dl>
<dl class="type">
<dt id="mps_fmt_fwd_t">
void <tt class="descname">(*mps_fmt_fwd_t)</tt><big>(</big><a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;old</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;new</em><big>)</big><a class="headerlink" href="#mps_fmt_fwd_t" title="Permalink to this definition"></a></dt>
<dd><p>The type of the <a class="reference internal" href="../glossary/f.html#term-forward-method"><em class="xref std std-term">forward method</em></a> of an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">old</span></tt> is the address of an object.</p>
<p><tt class="docutils literal"><span class="pre">new</span></tt> is the address to where the object has been moved.</p>
<p>The MPS calls the forward method for an object format when it has
relocated an object belonging to that format. The forward method
must replace the object at <tt class="docutils literal"><span class="pre">old</span></tt> with a <a class="reference internal" href="../glossary/f.html#term-forwarding-marker"><em class="xref std std-term">forwarding marker</em></a>
that points to the address &#8216;new&#8217;. The forwarding marker must meet
the following requirements:</p>
<ol class="arabic simple">
<li>It must be possible for the MPS to call other methods in the
object format (the <a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan method</em></a>, the <a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip method</em></a>
and so on) with the address of a forwarding marker as the
argument.</li>
<li>The forwarding marker must not be bigger than the original
object.</li>
<li>It must be possible for the <a class="reference internal" href="../glossary/i.html#term-is-forwarded-method"><em class="xref std std-term">is-forwarded method</em></a> of the
object format to distinguish the forwarding marker from
ordinary objects, and the is-forwarded method method must
return the address <tt class="docutils literal"><span class="pre">new</span></tt>. See <a class="reference internal" href="#mps_fmt_isfwd_t" title="mps_fmt_isfwd_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_isfwd_t</span></tt></a>.</li>
</ol>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">This method is never invoked by the <a class="reference internal" href="../glossary/g.html#term-garbage-collector"><em class="xref std std-term">garbage collector</em></a>
on an object in a <a class="reference internal" href="../glossary/n.html#term-non-moving-garbage-collector"><em class="xref std std-term">non-moving</em></a> <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a>.</p>
</div>
</dd></dl>
<dl class="type">
<dt id="mps_fmt_isfwd_t">
<a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a> <tt class="descname">(*mps_fmt_isfwd_t)</tt><big>(</big><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_fmt_isfwd_t" title="Permalink to this definition"></a></dt>
<dd><p>The type of the <a class="reference internal" href="../glossary/i.html#term-is-forwarded-method"><em class="xref std std-term">is-forwarded method</em></a> of an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object
format</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">addr</span></tt> is the address of a candidate object.</p>
<p>If the <tt class="docutils literal"><span class="pre">addr</span></tt> is the address of a <a class="reference internal" href="../glossary/f.html#term-forwarding-object"><em class="xref std std-term">forwarding object</em></a>, return
the address where the object was moved to. This must be the value
of the <tt class="docutils literal"><span class="pre">new</span></tt> argument supplied to the <a class="reference internal" href="../glossary/f.html#term-forward-method"><em class="xref std std-term">forward method</em></a> when
the object was moved. If not, return a null pointer.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">This method is never invoked by the <a class="reference internal" href="../glossary/g.html#term-garbage-collector"><em class="xref std std-term">garbage collector</em></a>
on an object in a <a class="reference internal" href="../glossary/n.html#term-non-moving-garbage-collector"><em class="xref std std-term">non-moving</em></a> <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a>.</p>
</div>
</dd></dl>
<dl class="type">
<dt id="mps_fmt_pad_t">
void <tt class="descname">(*mps_fmt_pad_t)</tt><big>(</big><a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;addr</em>, size_t<em>&nbsp;size</em><big>)</big><a class="headerlink" href="#mps_fmt_pad_t" title="Permalink to this definition"></a></dt>
<dd><p>The type of the <a class="reference internal" href="../glossary/p.html#term-padding-method"><em class="xref std std-term">padding method</em></a> of an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object
format</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">addr</span></tt> is the address at which to create a <a class="reference internal" href="../glossary/p.html#term-padding-object"><em class="xref std std-term">padding object</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">size</span></tt> is the <a class="reference internal" href="../glossary/s.html#term-size"><em class="xref std std-term">size</em></a> of the padding object to be created.</p>
<p>The MPS calls a padding method when it wants to create a padding
object. Typically the MPS creates padding objects to fill in
otherwise unused gaps in memory; they allow the MPS to pack
objects into fixed-size units (such as operating system
<a class="reference internal" href="../glossary/p.html#term-page"><em class="xref std std-term">pages</em></a>).</p>
<p>The padding method must create a padding object of the specified
size at the specified address. The size can be any aligned (to the
format alignment) size. A padding object must be acceptable to
other methods in the format (the <a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan method</em></a>, the
<a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip method</em></a>, and so on).</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">The padding method always receives a base pointer, even if the
object format has a non-zero
<tt class="xref c c-macro docutils literal"><span class="pre">MPS_KEY_FMT_HEADER_SIZE</span></tt>.</p>
</div>
</dd></dl>
<dl class="type">
<dt id="mps_fmt_scan_t">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">(*mps_fmt_scan_t)</tt><big>(</big><a class="reference internal" href="scanning.html#mps_ss_t" title="mps_ss_t">mps_ss_t</a><em>&nbsp;ss</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;base</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;limit</em><big>)</big><a class="headerlink" href="#mps_fmt_scan_t" title="Permalink to this definition"></a></dt>
<dd><p>The type of the <a class="reference internal" href="../glossary/s.html#term-scan-method"><em class="xref std std-term">scan method</em></a> of an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">ss</span></tt> is the <a class="reference internal" href="../glossary/s.html#term-scan-state"><em class="xref std std-term">scan state</em></a>. It must be passed to
<a class="reference internal" href="scanning.html#MPS_SCAN_BEGIN" title="MPS_SCAN_BEGIN"><tt class="xref c c-func docutils literal"><span class="pre">MPS_SCAN_BEGIN()</span></tt></a> and <a class="reference internal" href="scanning.html#MPS_SCAN_END" title="MPS_SCAN_END"><tt class="xref c c-func docutils literal"><span class="pre">MPS_SCAN_END()</span></tt></a> to delimit a
sequence of fix operations, and to the functions
<a class="reference internal" href="scanning.html#MPS_FIX1" title="MPS_FIX1"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX1()</span></tt></a> and <a class="reference internal" href="scanning.html#MPS_FIX2" title="MPS_FIX2"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX2()</span></tt></a> when fixing a
<a class="reference internal" href="../glossary/r.html#term-reference"><em class="xref std std-term">reference</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">base</span></tt> points to the first <a class="reference internal" href="../glossary/f.html#term-formatted-object"><em class="xref std std-term">formatted object</em></a> in the block
of memory to be scanned.</p>
<p><tt class="docutils literal"><span class="pre">limit</span></tt> points to the location just beyond the end of the block to
be scanned. Note that there might not be any object at this
location.</p>
<p>Returns a <a class="reference internal" href="../glossary/r.html#term-result-code"><em class="xref std std-term">result code</em></a>. If a fix function returns a value
other than <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>, the scan method must return that
value, and may return without fixing any further references.
Generally, it is better if it returns as soon as possible. If the
scanning is completed successfully, the function should 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>.</p>
<p>The scan method for an object format is called when the MPS needs
to scan objects in a block of memory containing objects belonging
to that format. The scan method is called with a scan state and
the base and limit of the block of objects to scan. It must then
indicate references within the objects by calling
<a class="reference internal" href="scanning.html#MPS_FIX1" title="MPS_FIX1"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX1()</span></tt></a> and <a class="reference internal" href="scanning.html#MPS_FIX2" title="MPS_FIX2"><tt class="xref c c-func docutils literal"><span class="pre">MPS_FIX2()</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="scanning.html#topic-scanning"><em>Scanning</em></a>.</p>
</div>
</dd></dl>
<dl class="type">
<dt id="mps_fmt_skip_t">
<a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a> <tt class="descname">(*mps_fmt_skip_t)</tt><big>(</big><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_fmt_skip_t" title="Permalink to this definition"></a></dt>
<dd><p>The type of the <a class="reference internal" href="../glossary/s.html#term-skip-method"><em class="xref std std-term">skip method</em></a> of an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">addr</span></tt> is the address of the object to be skipped.</p>
<p>Returns the address of the &#8220;next object&#8221;. In an object format
without headers (for example, a format of variant A), this is the
address just past the end of this object. In an object format with
<a class="reference internal" href="../glossary/i.html#term-in-band-header"><em class="xref std std-term">in-band headers</em></a>, it&#8217;s the address just past where the
header of next object would be, if there were one.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">In either case, the result is the sum of <tt class="docutils literal"><span class="pre">addr</span></tt> and the size
of the block containing the object.</p>
</div>
<p>A skip method is not allowed to fail.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">The MPS uses this method to determine the size of objects (by
subtracting <tt class="docutils literal"><span class="pre">addr</span></tt> from the result) as well as skipping over
them.</p>
</div>
</dd></dl>
</div>
<div class="section" id="object-format-introspection">
<span id="index-5"></span><h2>7.5. Object format introspection<a class="headerlink" href="#object-format-introspection" title="Permalink to this headline"></a></h2>
<dl class="function">
<dt id="mps_addr_fmt">
<a class="reference internal" href="interface.html#mps_bool_t" title="mps_bool_t">mps_bool_t</a> <tt class="descname">mps_addr_fmt</tt><big>(</big><a class="reference internal" href="#mps_fmt_t" title="mps_fmt_t">mps_fmt_t</a><em>&nbsp;*fmt_o</em>, <a class="reference internal" href="arena.html#mps_arena_t" title="mps_arena_t">mps_arena_t</a><em>&nbsp;arena</em>, <a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;addr</em><big>)</big><a class="headerlink" href="#mps_addr_fmt" title="Permalink to this definition"></a></dt>
<dd><p>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.</p>
<p><tt class="docutils literal"><span class="pre">fmt_o</span></tt> points to a location that will hold the address of the
object format, if one is found.</p>
<p><tt class="docutils literal"><span class="pre">arena</span></tt> is the arena whose object formats will be considered.</p>
<p><tt class="docutils literal"><span class="pre">addr</span></tt> is the address.</p>
<p>If <tt class="docutils literal"><span class="pre">addr</span></tt> is the address of a location inside a block allocated
from a pool in <tt class="docutils literal"><span class="pre">arena</span></tt>, and that pool has an object format, then
update the location pointed to by <tt class="docutils literal"><span class="pre">fmt_o</span></tt> with the address of
the object format, and return true.</p>
<p>If <tt class="docutils literal"><span class="pre">addr</span></tt> is the address of a location inside a block allocated
from a pool in <tt class="docutils literal"><span class="pre">arena</span></tt>, but that pool has no object format,
return false.</p>
<p>If <tt class="docutils literal"><span class="pre">addr</span></tt> points to a location that is not managed by <tt class="docutils literal"><span class="pre">arena</span></tt>,
return false.</p>
<p>If none of the above conditions is satisfied,
<a class="reference internal" href="#mps_addr_fmt" title="mps_addr_fmt"><tt class="xref c c-func docutils literal"><span class="pre">mps_addr_fmt()</span></tt></a> may return either true or false.</p>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">This function might return a false positive by returning true
if you ask about an address that happens to be inside memory
managed by a pool with an object format, but which is not
inside a block allocated by that pool. It never returns a
false negative.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="mps_arena_formatted_objects_walk">
void <tt class="descname">mps_arena_formatted_objects_walk</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_formatted_objects_stepper_t" title="mps_formatted_objects_stepper_t">mps_formatted_objects_stepper_t</a><em>&nbsp;f</em>, void<em>&nbsp;*p</em>, size_t<em>&nbsp;s</em><big>)</big><a class="headerlink" href="#mps_arena_formatted_objects_walk" title="Permalink to this definition"></a></dt>
<dd><p>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
<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 formatted objects you want to visit.</p>
<p><tt class="docutils literal"><span class="pre">f</span></tt> is a formatted objects stepper function. It will be called for
each formatted object in the arena. See
<a class="reference internal" href="#mps_formatted_objects_stepper_t" title="mps_formatted_objects_stepper_t"><tt class="xref c c-type docutils literal"><span class="pre">mps_formatted_objects_stepper_t</span></tt></a>.</p>
<p><tt class="docutils literal"><span class="pre">p</span></tt> and <tt class="docutils literal"><span class="pre">s</span></tt> are arguments that will be passed to <tt class="docutils literal"><span class="pre">f</span></tt> each time it
is called. This is intended to make it easy to pass, for example,
an array and its size as parameters.</p>
<p>Each <a class="reference internal" href="../glossary/p.html#term-pool-class"><em class="xref std std-term">pool class</em></a> determines for which objects the stepper
function is called. Typically, all validly formatted objects are
visited. During a <a class="reference internal" href="../glossary/t.html#term-trace"><em class="xref std std-term">trace</em></a> this will in general be only the
<a class="reference internal" href="../glossary/b.html#term-black"><em class="xref std std-term">black</em></a> objects, though the <a class="reference internal" href="../pool/lo.html#pool-lo"><em>LO (Leaf Object)</em></a> pool, for
example, will walk all objects since they are validly formatted
whether they are black or <a class="reference internal" href="../glossary/w.html#term-white"><em class="xref std std-term">white</em></a>. <a class="reference internal" href="../glossary/p.html#term-padding-object"><em class="xref std std-term">Padding objects</em></a>
may be visited at the pool class&#8217;s discretion: the <a class="reference internal" href="../glossary/c.html#term-client-program"><em class="xref std std-term">client
program</em></a> should handle this case.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="arena.html#topic-arena"><em>Arenas</em></a>.</p>
</div>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last">This function is intended for heap analysis, tuning, and
debugging, not for frequent use in production.</p>
</div>
</dd></dl>
<dl class="type">
<dt id="mps_formatted_objects_stepper_t">
void <tt class="descname">(*mps_formatted_objects_stepper_t)</tt><big>(</big><a class="reference internal" href="interface.html#mps_addr_t" title="mps_addr_t">mps_addr_t</a><em>&nbsp;addr</em>, <a class="reference internal" href="#mps_fmt_t" title="mps_fmt_t">mps_fmt_t</a><em>&nbsp;fmt</em>, <a class="reference internal" href="pool.html#mps_pool_t" title="mps_pool_t">mps_pool_t</a><em>&nbsp;pool</em>, void<em>&nbsp;*p</em>, size_t<em>&nbsp;s</em><big>)</big><a class="headerlink" href="#mps_formatted_objects_stepper_t" title="Permalink to this definition"></a></dt>
<dd><p>The type of a <a class="reference internal" href="../glossary/f.html#term-formatted-object"><em class="xref std std-term">formatted objects</em></a>
<a class="reference internal" href="../glossary/s.html#term-stepper-function"><em class="xref std std-term">stepper function</em></a>.</p>
<p>A function of this type can be passed to
<a class="reference internal" href="#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>, in which case it will
be called for each formatted object in an <a class="reference internal" href="../glossary/a.html#term-arena"><em class="xref std std-term">arena</em></a>. It
receives five arguments:</p>
<p><tt class="docutils literal"><span class="pre">addr</span></tt> is the address of the object.</p>
<p><tt class="docutils literal"><span class="pre">fmt</span></tt> is the <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> for that object.</p>
<p><tt class="docutils literal"><span class="pre">pool</span></tt> is the <a class="reference internal" href="../glossary/p.html#term-pool"><em class="xref std std-term">pool</em></a> to which the object belongs.</p>
<p><tt class="docutils literal"><span class="pre">p</span></tt> and <tt class="docutils literal"><span class="pre">s</span></tt> are the corresponding values that were passed to
<a class="reference internal" href="#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>.</p>
<p>The function may not call any function in the MPS. It may access:</p>
<ol class="loweralpha simple">
<li>memory inside the object or block pointed to by <tt class="docutils literal"><span class="pre">addr</span></tt>;</li>
<li>memory managed by the MPS that is in pools that do not protect
their contents;</li>
<li>memory not managed by the MPS;</li>
</ol>
<p>It must not access other memory managed by the MPS.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="arena.html#topic-arena"><em>Arenas</em></a>.</p>
</div>
</dd></dl>
</div>
<div class="section" id="obsolete-interface">
<h2>7.6. Obsolete interface<a class="headerlink" href="#obsolete-interface" title="Permalink to this headline"></a></h2>
<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="allocation.html#mps_ap_create_k" title="mps_ap_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_ap_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 flexible and easier to understand.</p>
</div>
<p>Formerly the only way to create object formats was to describe the
format in the form of a <em>format variant structure</em>.</p>
<p>There are four format variants.</p>
<ul class="simple">
<li>Variant A (<a class="reference internal" href="#mps_fmt_A_s" title="mps_fmt_A_s"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_A_s</span></tt></a>): for objects without
<a class="reference internal" href="../glossary/i.html#term-in-band-header"><em class="xref std std-term">headers</em></a>.</li>
<li>Variant B (<a class="reference internal" href="#mps_fmt_B_s" title="mps_fmt_B_s"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_B_s</span></tt></a>): as variant A, but with the
addition of a class method.</li>
<li>Variant auto-header (<a class="reference internal" href="#mps_fmt_auto_header_s" title="mps_fmt_auto_header_s"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_auto_header_s</span></tt></a>): for objects
with <a class="reference internal" href="../glossary/i.html#term-in-band-header"><em class="xref std std-term">in-band headers</em></a>.</li>
<li>Variant fixed (<a class="reference internal" href="#mps_fmt_fixed_s" title="mps_fmt_fixed_s"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_fixed_s</span></tt></a>): for fixed-size objects.</li>
</ul>
<p>The client program creates an object format by construct a format
variant structure and then calling the appropriate <tt class="docutils literal"><span class="pre">mps_fmt_create_</span></tt>
function for the variant. The variant structure can then be disposed
of.</p>
<dl class="type">
<dt id="mps_fmt_A_s">
<tt class="descname">mps_fmt_A_s</tt><a class="headerlink" href="#mps_fmt_A_s" title="Permalink to this definition"></a></dt>
<dd><p>The type of the structure used to create an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>
of variant A.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">mps_fmt_A_s</span> <span class="p">{</span>
<span class="kt">mps_align_t</span> <span class="n">align</span><span class="p">;</span>
<span class="kt">mps_fmt_scan_t</span> <span class="n">scan</span><span class="p">;</span>
<span class="kt">mps_fmt_skip_t</span> <span class="n">skip</span><span class="p">;</span>
<span class="kt">mps_fmt_copy_t</span> <span class="n">copy</span><span class="p">;</span>
<span class="kt">mps_fmt_fwd_t</span> <span class="n">fwd</span><span class="p">;</span>
<span class="kt">mps_fmt_isfwd_t</span> <span class="n">isfwd</span><span class="p">;</span>
<span class="kt">mps_fmt_pad_t</span> <span class="n">pad</span><span class="p">;</span>
<span class="p">}</span> <span class="n">mps_fmt_A_s</span><span class="p">;</span>
</pre></div>
</div>
<p>The fields of this structure correspond to the keyword arguments
to <a class="reference internal" href="#mps_fmt_create_k" title="mps_fmt_create_k"><tt class="xref c c-func docutils literal"><span class="pre">mps_fmt_create_k()</span></tt></a>, except for <tt class="docutils literal"><span class="pre">copy</span></tt>, which is not
used. In older versions of the MPS this was a <a class="reference internal" href="../glossary/c.html#term-copy-method"><em class="xref std std-term">copy method</em></a>
that copied objects belonging to this format.</p>
</dd></dl>
<dl class="function">
<dt id="mps_fmt_create_A">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_fmt_create_A</tt><big>(</big><a class="reference internal" href="#mps_fmt_t" title="mps_fmt_t">mps_fmt_t</a><em>&nbsp;*fmt_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_fmt_A_s" title="mps_fmt_A_s">mps_fmt_A_s</a><em>&nbsp;*fmt_A</em><big>)</big><a class="headerlink" href="#mps_fmt_create_A" title="Permalink to this definition"></a></dt>
<dd><p>Create an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> based on a description of an
object format of variant A.</p>
</dd></dl>
<dl class="type">
<dt id="mps_fmt_B_s">
<tt class="descname">mps_fmt_B_s</tt><a class="headerlink" href="#mps_fmt_B_s" title="Permalink to this definition"></a></dt>
<dd><p>The type of the structure used to create an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>
of variant B.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">mps_fmt_B_s</span> <span class="p">{</span>
<span class="kt">mps_align_t</span> <span class="n">align</span><span class="p">;</span>
<span class="kt">mps_fmt_scan_t</span> <span class="n">scan</span><span class="p">;</span>
<span class="kt">mps_fmt_skip_t</span> <span class="n">skip</span><span class="p">;</span>
<span class="kt">mps_fmt_copy_t</span> <span class="n">copy</span><span class="p">;</span>
<span class="kt">mps_fmt_fwd_t</span> <span class="n">fwd</span><span class="p">;</span>
<span class="kt">mps_fmt_isfwd_t</span> <span class="n">isfwd</span><span class="p">;</span>
<span class="kt">mps_fmt_pad_t</span> <span class="n">pad</span><span class="p">;</span>
<span class="kt">mps_fmt_class_t</span> <span class="n">mps_class</span><span class="p">;</span>
<span class="p">}</span> <span class="n">mps_fmt_B_s</span><span class="p">;</span>
</pre></div>
</div>
<p>Variant B is the same as variant A except for the addition of the
<tt class="docutils literal"><span class="pre">mps_class</span></tt> method. See <a class="reference internal" href="#mps_fmt_A_s" title="mps_fmt_A_s"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_A_s</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="mps_fmt_create_B">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_fmt_create_B</tt><big>(</big><a class="reference internal" href="#mps_fmt_t" title="mps_fmt_t">mps_fmt_t</a><em>&nbsp;*fmt_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_fmt_B_s" title="mps_fmt_B_s">mps_fmt_B_s</a><em>&nbsp;*fmt_B</em><big>)</big><a class="headerlink" href="#mps_fmt_create_B" title="Permalink to this definition"></a></dt>
<dd><p>Create an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> based on a description of an
object format of variant B.</p>
</dd></dl>
<dl class="type">
<dt id="mps_fmt_auto_header_s">
<tt class="descname">mps_fmt_auto_header_s</tt><a class="headerlink" href="#mps_fmt_auto_header_s" title="Permalink to this definition"></a></dt>
<dd><p>The type of the structure used to create an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>
of variant auto-header.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">mps_fmt_auto_header_s</span> <span class="p">{</span>
<span class="kt">mps_align_t</span> <span class="n">align</span><span class="p">;</span>
<span class="kt">mps_fmt_scan_t</span> <span class="n">scan</span><span class="p">;</span>
<span class="kt">mps_fmt_skip_t</span> <span class="n">skip</span><span class="p">;</span>
<span class="kt">mps_fmt_fwd_t</span> <span class="n">fwd</span><span class="p">;</span>
<span class="kt">mps_fmt_isfwd_t</span> <span class="n">isfwd</span><span class="p">;</span>
<span class="kt">mps_fmt_pad_t</span> <span class="n">pad</span><span class="p">;</span>
<span class="kt">size_t</span> <span class="n">mps_headerSize</span><span class="p">;</span>
<span class="p">}</span> <span class="n">mps_fmt_auto_header_s</span><span class="p">;</span>
</pre></div>
</div>
<p>Variant auto-header is the same as variant A except for the
removal of the unused <tt class="docutils literal"><span class="pre">copy</span></tt> method, and the addition of the
<tt class="docutils literal"><span class="pre">mps_headerSize</span></tt> field. See <a class="reference internal" href="#mps_fmt_A_s" title="mps_fmt_A_s"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_A_s</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="mps_fmt_create_auto_header">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_fmt_create_auto_header</tt><big>(</big><a class="reference internal" href="#mps_fmt_t" title="mps_fmt_t">mps_fmt_t</a><em>&nbsp;*fmt_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_fmt_auto_header_s" title="mps_fmt_auto_header_s">mps_fmt_auto_header_s</a><em>&nbsp;*fmt_ah</em><big>)</big><a class="headerlink" href="#mps_fmt_create_auto_header" title="Permalink to this definition"></a></dt>
<dd><p>Create an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> based on a description of an
object format of variant auto-header.</p>
</dd></dl>
<dl class="type">
<dt id="mps_fmt_fixed_s">
<tt class="descname">mps_fmt_fixed_s</tt><a class="headerlink" href="#mps_fmt_fixed_s" title="Permalink to this definition"></a></dt>
<dd><p>The type of the structure used to create an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a>
of variant fixed.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="n">mps_fmt_fixed_s</span> <span class="p">{</span>
<span class="kt">mps_align_t</span> <span class="n">align</span><span class="p">;</span>
<span class="kt">mps_fmt_scan_t</span> <span class="n">scan</span><span class="p">;</span>
<span class="kt">mps_fmt_fwd_t</span> <span class="n">fwd</span><span class="p">;</span>
<span class="kt">mps_fmt_isfwd_t</span> <span class="n">isfwd</span><span class="p">;</span>
<span class="kt">mps_fmt_pad_t</span> <span class="n">pad</span><span class="p">;</span>
<span class="p">}</span> <span class="n">mps_fmt_fixed_s</span><span class="p">;</span>
</pre></div>
</div>
<p>Variant fixed is the same as variant A except for the removal of
the unused <tt class="docutils literal"><span class="pre">copy</span></tt> method, and the lack of a <tt class="docutils literal"><span class="pre">skip</span></tt> method
(this is not needed because the objects are fixed in size). See
<a class="reference internal" href="#mps_fmt_A_s" title="mps_fmt_A_s"><tt class="xref c c-type docutils literal"><span class="pre">mps_fmt_A_s</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="mps_fmt_create_fixed">
<a class="reference internal" href="error.html#mps_res_t" title="mps_res_t">mps_res_t</a> <tt class="descname">mps_fmt_create_fixed</tt><big>(</big><a class="reference internal" href="#mps_fmt_t" title="mps_fmt_t">mps_fmt_t</a><em>&nbsp;*fmt_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_fmt_fixed_s" title="mps_fmt_fixed_s">mps_fmt_fixed_s</a><em>&nbsp;*fmt_fixed</em><big>)</big><a class="headerlink" href="#mps_fmt_create_fixed" title="Permalink to this definition"></a></dt>
<dd><p>Create an <a class="reference internal" href="../glossary/o.html#term-object-format"><em class="xref std std-term">object format</em></a> based on a description of an
object format of variant fixed.</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="#">7. Object formats</a><ul>
<li><a class="reference internal" href="#interface">7.1. Interface</a></li>
<li><a class="reference internal" href="#in-band-headers">7.2. In-band headers</a></li>
<li><a class="reference internal" href="#cautions">7.3. Cautions</a></li>
<li><a class="reference internal" href="#format-methods">7.4. Format methods</a></li>
<li><a class="reference internal" href="#object-format-introspection">7.5. Object format introspection</a></li>
<li><a class="reference internal" href="#obsolete-interface">7.6. Obsolete interface</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="allocation.html"
title="previous chapter">6. Allocation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="scanning.html"
title="next chapter">8. Scanning</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="scanning.html" title="8. Scanning"
>next</a> |</li>
<li class="right" >
<a href="allocation.html" title="6. Allocation"
>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