mirror of
https://github.com/ganelson/inform.git
synced 2024-07-18 15:04:25 +03:00
472 lines
42 KiB
HTML
472 lines
42 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>What This Module Does</title>
|
|
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<meta name="viewport" content="width=device-width initial-scale=1">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta http-equiv="Content-Language" content="en-gb">
|
|
|
|
<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<script src="http://code.jquery.com/jquery-1.12.4.min.js"
|
|
integrity="sha256-ZosEbRLbNQzLpnKIkEdrPv7lOy9C27hHQ+Xp8a4MxAQ=" crossorigin="anonymous"></script>
|
|
|
|
<script src="../docs-assets/Bigfoot.js"></script>
|
|
<link href="../docs-assets/Bigfoot.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
|
|
</head>
|
|
<body class="commentary-font">
|
|
<nav role="navigation">
|
|
<h1><a href="../index.html">
|
|
<img src="../docs-assets/Inform.png" height=72">
|
|
</a></h1>
|
|
<ul><li><a href="../compiler.html">compiler tools</a></li>
|
|
<li><a href="../other.html">other tools</a></li>
|
|
<li><a href="../extensions.html">extensions and kits</a></li>
|
|
<li><a href="../units.html">unit test tools</a></li>
|
|
</ul><h2>Compiler Webs</h2><ul>
|
|
<li><a href="../inbuild/index.html">inbuild</a></li>
|
|
<li><a href="../inform7/index.html">inform7</a></li>
|
|
<li><a href="../inter/index.html">inter</a></li>
|
|
</ul><h2>Inbuild Modules</h2><ul>
|
|
<li><a href="../supervisor-module/index.html">supervisor</a></li>
|
|
</ul><h2>Inform7 Modules</h2><ul>
|
|
<li><a href="../core-module/index.html">core</a></li>
|
|
<li><a href="../assertions-module/index.html">assertions</a></li>
|
|
<li><a href="../values-module/index.html">values</a></li>
|
|
<li><a href="../knowledge-module/index.html">knowledge</a></li>
|
|
<li><a href="../imperative-module/index.html">imperative</a></li>
|
|
<li><a href="../runtime-module/index.html">runtime</a></li>
|
|
<li><a href="../if-module/index.html">if</a></li>
|
|
<li><a href="../multimedia-module/index.html">multimedia</a></li>
|
|
<li><a href="../index-module/index.html">index</a></li>
|
|
</ul><h2>Inter Modules</h2><ul>
|
|
<li><a href="index.html"><span class="selectedlink">bytecode</span></a></li>
|
|
<li><a href="../building-module/index.html">building</a></li>
|
|
<li><a href="../pipeline-module/index.html">pipeline</a></li>
|
|
<li><a href="../final-module/index.html">final</a></li>
|
|
</ul><h2>Services</h2><ul>
|
|
<li><a href="../arch-module/index.html">arch</a></li>
|
|
<li><a href="../calculus-module/index.html">calculus</a></li>
|
|
<li><a href="../html-module/index.html">html</a></li>
|
|
<li><a href="../inflections-module/index.html">inflections</a></li>
|
|
<li><a href="../kinds-module/index.html">kinds</a></li>
|
|
<li><a href="../linguistics-module/index.html">linguistics</a></li>
|
|
<li><a href="../problems-module/index.html">problems</a></li>
|
|
<li><a href="../syntax-module/index.html">syntax</a></li>
|
|
<li><a href="../words-module/index.html">words</a></li>
|
|
<li><a href="../../../inweb/docs/foundation-module/index.html">foundation</a></li>
|
|
|
|
</ul>
|
|
</nav>
|
|
<main role="main">
|
|
<!--Weave of 'What This Module Does' generated by Inweb-->
|
|
<div class="breadcrumbs">
|
|
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="../compiler.html">Inter Modules</a></li><li><a href="index.html">bytecode</a></li><li><a href="index.html#P">Preliminaries</a></li><li><b>What This Module Does</b></li></ul></div>
|
|
<p class="purpose">An overview of the bytecode module's role and abilities.</p>
|
|
|
|
<ul class="toc"><li><a href="P-wtmd.html#SP1">§1. Prerequisites</a></li><li><a href="P-wtmd.html#SP2">§2. What is intermediate about inter</a></li><li><a href="P-wtmd.html#SP4">§4. Packages</a></li><li><a href="P-wtmd.html#SP5">§5. Symbols</a></li><li><a href="P-wtmd.html#SP9">§9. The warehouse and the building site</a></li><li><a href="P-wtmd.html#SP10">§10. Nodes and instructions</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>§1. Prerequisites. </b>The bytecode module is a part of the Inform compiler toolset. It is
|
|
presented as a literate program or "web". Before diving in:
|
|
</p>
|
|
|
|
<ul class="items"><li>(a) It helps to have some experience of reading webs: see <a href="../../../inweb/docs/index.html" class="internal">inweb</a> for more.
|
|
</li><li>(b) The module is written in C, in fact ANSI C99, but this is disguised by the
|
|
fact that it uses some extension syntaxes provided by the <a href="../../../inweb/docs/index.html" class="internal">inweb</a> literate
|
|
programming tool, making it a dialect of C called InC. See <a href="../../../inweb/docs/index.html" class="internal">inweb</a> for
|
|
full details, but essentially: it's C without predeclarations or header files,
|
|
and where functions have names like <span class="extract"><span class="extract-syntax">Tags::add_by_name</span></span> rather than just <span class="extract"><span class="extract-syntax">add_by_name</span></span>.
|
|
</li><li>(c) This module uses other modules drawn from the <a href="../compiler.html" class="internal">compiler</a>, and also
|
|
uses a module of utility functions called <a href="../../../inweb/docs/foundation-module/index.html" class="internal">foundation</a>.
|
|
For more, see <a href="../../../inweb/docs/foundation-module/P-abgtf.html" class="internal">A Brief Guide to Foundation (in foundation)</a>.
|
|
</li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>§2. What is intermediate about inter. </b>This module is concerned with managing the <a href="2-it.html#SP1" class="internal">inter_tree</a> data structure in
|
|
memory, and with reading and writing it from and to the filing system. Because
|
|
this data structure can live in files outside of memory, we need to worry about
|
|
whether its design changes over time: see <a href="1-tiv.html" class="internal">The Inter Version</a> for the issues
|
|
arising over that.
|
|
</p>
|
|
|
|
<p class="commentary">An Inter tree is an expression of a single program. It's an intermediate state
|
|
between the source code for that program — perhaps Inform 7 source text,
|
|
perhaps Inform 6-syntax source for a kit — and the so-called "final" output,
|
|
typically a C or I6 program.
|
|
</p>
|
|
|
|
<p class="commentary">In conventional compiler design, a high-level language such as Swift or C# is
|
|
parsed first into an abstract syntax tree, or "AST", which is essentially a tree
|
|
representation of the syntax but is marked up with semantic information about
|
|
what everything in it means. This AST is then compiled down to an intermediate
|
|
representation, an "IR", which is a sort of structured list of still-abstract
|
|
operations to perform. The IR is then further converted to produce the compiler's
|
|
actual output. Thus:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="element-syntax">source</span><span class="plain-syntax"> ----> </span><span class="function-syntax">AST</span><span class="plain-syntax"> ------------> </span><span class="function-syntax">IR</span><span class="plain-syntax"> ----> </span><span class="element-syntax">output</span><span class="plain-syntax"> (</span><span class="element-syntax">e</span><span class="plain-syntax">.</span><span class="element-syntax">g</span><span class="plain-syntax">., </span><span class="element-syntax">assembly</span><span class="plain-syntax"> </span><span class="element-syntax">language</span><span class="plain-syntax">)</span>
|
|
</pre>
|
|
<p class="commentary">In the Inform family of tools, two languages have to be compiled: natural
|
|
language by <a href="../inform7/index.html" class="internal">inform7</a> and more conventional C-like code by <a href="../inter/index.html" class="internal">inter</a>.
|
|
Having very different syntaxes, these have different ASTs:
|
|
</p>
|
|
|
|
<ul class="items"><li>● For I7, a <span class="extract"><span class="extract-syntax">parse_node_tree</span></span>, managed by the <a href="../syntax-module/index.html" class="internal">syntax</a> module.
|
|
</li><li>● For Inter, an <span class="extract"><span class="extract-syntax">inter_schema</span></span>, managed by the <a href="../building-module/index.html" class="internal">building</a> module.
|
|
</li></ul>
|
|
<p class="commentary">But these two compiler flows share the same IR — an <a href="2-it.html#SP1" class="internal">inter_tree</a> provides the
|
|
intermediate representation for both:<sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup>
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> "</span><span class="function-syntax">AST</span><span class="plain-syntax">" "</span><span class="function-syntax">IR</span><span class="plain-syntax">"</span>
|
|
<span class="plain-syntax"> </span><span class="element-syntax">source</span><span class="plain-syntax"> </span><span class="element-syntax">syntax</span>
|
|
<span class="plain-syntax"> </span><span class="element-syntax">text</span><span class="plain-syntax"> ---> </span><span class="element-syntax">tree</span><span class="plain-syntax"> -------+</span>
|
|
<span class="plain-syntax"> </span><span class="function-syntax">INFORM7</span><span class="plain-syntax"> \</span>
|
|
<span class="plain-syntax"> \</span>
|
|
<span class="plain-syntax"> ----> </span><span class="element-syntax">Inter</span><span class="plain-syntax"> ----> </span><span class="element-syntax">output</span><span class="plain-syntax"> (</span><span class="element-syntax">e</span><span class="plain-syntax">.</span><span class="element-syntax">g</span><span class="plain-syntax">., </span><span class="element-syntax">C</span><span class="plain-syntax"> </span><span class="element-syntax">or</span><span class="plain-syntax"> </span><span class="element-syntax">Inform</span><span class="plain-syntax"> </span><span class="constant-syntax">6</span><span class="plain-syntax"> </span><span class="element-syntax">code</span><span class="plain-syntax">)</span>
|
|
<span class="plain-syntax"> / </span><span class="element-syntax">tree</span>
|
|
<span class="plain-syntax"> </span><span class="element-syntax">kit</span><span class="plain-syntax"> </span><span class="element-syntax">Inter</span><span class="plain-syntax"> /</span>
|
|
<span class="plain-syntax"> </span><span class="element-syntax">source</span><span class="plain-syntax"> ---> </span><span class="element-syntax">schemas</span><span class="plain-syntax"> -----+</span>
|
|
<span class="plain-syntax"> </span><span class="function-syntax">INTER</span>
|
|
</pre>
|
|
<p class="commentary">Because we want to work with hybrid programs, part compiled by one flow and
|
|
part by the other, Inter is not quite as low-level as most IRs.<sup id="fnref:2"><a href="#fn:2" rel="footnote">2</a></sup> It still
|
|
contains a great deal of semantic markup, making analysis and optimisation
|
|
feasible. (Not very much of this is actually done at present, but see e.g.
|
|
<a href="../pipeline-module/6-eros.html" class="internal">Eliminate Redundant Operations Stage (in pipeline)</a>.)
|
|
</p>
|
|
|
|
<ul class="footnotetexts"><li class="footnote" id="fn:1"><p class="inwebfootnote"><sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup> In fact Inter schemas are so useful as a tool for generating short runs of
|
|
Inter that the main <a href="../inform7/index.html" class="internal">inform7</a> compiler also uses them from time to time, but
|
|
not directly to represent the source text.
|
|
<a href="#fnref:1" title="return to text"> ↩</a></p></li><li class="footnote" id="fn:2"><p class="inwebfootnote"><sup id="fnref:2"><a href="#fn:2" rel="footnote">2</a></sup> Though IRs vary considerably. Microsoft's Common Intermediate Language (CIL),
|
|
used as a back-end by C#, has quite low-level bytecode but stores it in a
|
|
highly structured object-oriented way.
|
|
<a href="#fnref:2" title="return to text"> ↩</a></p></li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>§3. </b>Inter trees can be saved out as files in either binary or textual form;
|
|
binary form being much faster to load back in, textual much easier to read
|
|
and check over.
|
|
</p>
|
|
|
|
<p class="commentary">It is even possible to write Inter programs by hand, using a text editor. To
|
|
get a sense of what that looks like, see the manual <a href="../inter/M-ti.html" class="internal">Textual Inter (in inter)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>§4. Packages. </b>The main organising idea of Inter trees is the <a href="2-pck.html#SP2" class="internal">inter_package</a>. <a href="2-pck.html" class="internal">Packages</a> are
|
|
like nested boxes: each one can hold either more packages, or Inter instructions
|
|
providing code or data, or both.
|
|
</p>
|
|
|
|
<p class="commentary">Each package has a name, and its location can be identified by a "URL". For
|
|
example, <span class="extract"><span class="extract-syntax">/main/BasicInformKit/properties</span></span> means "the package <span class="extract"><span class="extract-syntax">properties</span></span>
|
|
inside the package <span class="extract"><span class="extract-syntax">BasicInformKit</span></span> inside the package <span class="extract"><span class="extract-syntax">main</span></span>".
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">....................................................</span>
|
|
<span class="plain-syntax">. </span><span class="element-syntax">top</span><span class="plain-syntax">-</span><span class="element-syntax">level</span><span class="plain-syntax"> </span><span class="element-syntax">material</span><span class="plain-syntax"> .</span>
|
|
<span class="plain-syntax">. +--------------------------------------------+ .</span>
|
|
<span class="plain-syntax">. | /</span><span class="element-syntax">main</span><span class="plain-syntax"> | .</span>
|
|
<span class="plain-syntax">. | +-------------------------------------+ | .</span>
|
|
<span class="plain-syntax">. | | /</span><span class="element-syntax">main</span><span class="plain-syntax">/</span><span class="element-syntax">BasicInformKit</span><span class="plain-syntax"> | | .</span>
|
|
<span class="plain-syntax">. | | +---------------------------------+ | | .</span>
|
|
<span class="plain-syntax">. | | | /</span><span class="element-syntax">main</span><span class="plain-syntax">/</span><span class="element-syntax">BasicInformKit</span><span class="plain-syntax">/</span><span class="element-syntax">variables</span><span class="plain-syntax"> | | | .</span>
|
|
<span class="plain-syntax">. | | +---------------------------------+ | | .</span>
|
|
<span class="plain-syntax">. | | +---------------------------------+ | | .</span>
|
|
<span class="plain-syntax">. | | | /</span><span class="element-syntax">main</span><span class="plain-syntax">/</span><span class="element-syntax">BasicInformKit</span><span class="plain-syntax">/</span><span class="element-syntax">properties</span><span class="plain-syntax"> | | | .</span>
|
|
<span class="plain-syntax">. | | +---------------------------------+ | | .</span>
|
|
<span class="plain-syntax">. | | ... | | .</span>
|
|
<span class="plain-syntax">. | +-------------------------------------+ | .</span>
|
|
<span class="plain-syntax">. | ... | .</span>
|
|
<span class="plain-syntax">. +--------------------------------------------+ .</span>
|
|
<span class="plain-syntax">....................................................</span>
|
|
</pre>
|
|
<p class="commentary">Material at the root level is implemented as if it were in a special package
|
|
called the "root package" (the dotted box around everything in the diagram),
|
|
which has the empty name and thus the URL <span class="extract"><span class="extract-syntax">/</span></span>. But this is not really a
|
|
package, and follows different rules from all others.
|
|
</p>
|
|
|
|
<p class="commentary">For the conventions on how the Inform tool-chain sets up this hierarchy of
|
|
packages, see the <a href="../building-module/index.html" class="internal">building</a> module: that's not our concern here. We
|
|
simply provide infrastructure allowing pretty general hierarchies to be made.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>§5. Symbols. </b>Packages provide <a href="2-st.html" class="internal">Symbols Tables</a>: in fact, each package has its own
|
|
symbols table, which records identifier names and their meanings
|
|
within that package. For example, if a package <span class="extract"><span class="extract-syntax">X</span></span> contains a definition of a
|
|
constant called <span class="extract"><span class="extract-syntax">pi</span></span>, then the definition will occupy an Inter instruction
|
|
inside the package, and the identifier name <span class="extract"><span class="extract-syntax">pi</span></span> will be an <a href="2-sym.html#SP1" class="internal">inter_symbol</a>
|
|
recorded in its <a href="2-st.html#SP1" class="internal">inter_symbols_table</a>.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> +-------------------------+</span>
|
|
<span class="plain-syntax"> | </span><span class="element-syntax">Package</span><span class="plain-syntax"> </span><span class="element-syntax">X</span><span class="plain-syntax"> |</span>
|
|
<span class="plain-syntax"> | |</span>
|
|
<span class="plain-syntax"> | </span><span class="element-syntax">pi</span><span class="plain-syntax"> |</span>
|
|
<span class="plain-syntax"> | ..... |</span>
|
|
<span class="plain-syntax"> | </span><span class="element-syntax">constant</span><span class="plain-syntax"> </span><span class="element-syntax">K_int32</span><span class="plain-syntax"> </span><span class="element-syntax">pi</span><span class="plain-syntax"> = </span><span class="constant-syntax">3</span><span class="plain-syntax"> |</span>
|
|
<span class="plain-syntax"> +-------------------------+</span>
|
|
</pre>
|
|
<p class="commentary">The symbols table for the root package is special, and represents global
|
|
meanings accessible everywhere. But they are used only for concepts needed
|
|
by Inter itself, such as the identities of primitives like <span class="extract"><span class="extract-syntax">!add</span></span> or
|
|
<span class="extract"><span class="extract-syntax">!printnumber</span></span>. In some sense, they specify the kind of Inter tree we have,
|
|
rather than anything about the program it represents. Material from that
|
|
program — a variable, say, or a function — is not allowed at the root level.
|
|
</p>
|
|
|
|
<p class="commentary">Symbols can be annotated in various ways. See <a href="2-ann.html" class="internal">Annotations</a>. They also come
|
|
in several types, see <a href="2-sym.html#SP5" class="internal">InterSymbol::get_type</a>, and can have a few flags,
|
|
see <a href="2-sym.html#SP6" class="internal">InterSymbol::get_flag</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>§6. </b>The bytecode in a package can only refer to resources using symbols in that
|
|
same package. On the face of it, that means packages are so well sealed up
|
|
that they might as well all be independent programs, unable to see each other's
|
|
variables, constants and functions.
|
|
</p>
|
|
|
|
<p class="commentary">But that is not true because symbols in one package can be "wired" to symbols
|
|
in another:<sup id="fnref:3"><a href="#fn:3" rel="footnote">3</a></sup> see <a href="2-tw2.html" class="internal">The Wiring</a>. We write <span class="extract"><span class="extract-syntax">S ~~> T</span></span> if the symbol <span class="extract"><span class="extract-syntax">S</span></span> is "wired to"
|
|
<span class="extract"><span class="extract-syntax">T</span></span>, and we understand this as meaning that <span class="extract"><span class="extract-syntax">S</span></span> means whatever <span class="extract"><span class="extract-syntax">T</span></span> does.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> +-----------------+ +-------------------------------+</span>
|
|
<span class="plain-syntax"> | </span><span class="element-syntax">Package</span><span class="plain-syntax"> </span><span class="element-syntax">X</span><span class="plain-syntax"> | | </span><span class="element-syntax">Package</span><span class="plain-syntax"> </span><span class="element-syntax">Y</span><span class="plain-syntax"> |</span>
|
|
<span class="plain-syntax"> | | | |</span>
|
|
<span class="plain-syntax"> | </span><span class="element-syntax">earth</span><span class="plain-syntax"> ~~~~~~~~~~~~~~~~~~~~> </span><span class="element-syntax">earth</span><span class="plain-syntax"> |</span>
|
|
<span class="plain-syntax"> +-----------------+ | ..... |</span>
|
|
<span class="plain-syntax"> | </span><span class="element-syntax">variable</span><span class="plain-syntax"> </span><span class="element-syntax">K_int32</span><span class="plain-syntax"> </span><span class="element-syntax">earth</span><span class="plain-syntax"> = </span><span class="constant-syntax">7</span><span class="plain-syntax"> |</span>
|
|
<span class="plain-syntax"> +-------------------------------+</span>
|
|
</pre>
|
|
<p class="commentary">In this example, the symbol <span class="extract"><span class="extract-syntax">earth</span></span> in package <span class="extract"><span class="extract-syntax">X</span></span> is undefined. Instead it is
|
|
wired to a different symbol of the same name in package <span class="extract"><span class="extract-syntax">Y</span></span>, which is defined
|
|
as the name of a variable declared in that package. (The names do not have to
|
|
be the same, but they often are.)
|
|
</p>
|
|
|
|
<p class="commentary">Wiring is directional: <span class="extract"><span class="extract-syntax">S ~~> T</span></span> very definitely does not mean that <span class="extract"><span class="extract-syntax">T ~~> S</span></span>,
|
|
and indeed circuits are forbidden, because <span class="extract"><span class="extract-syntax">S1 ~~> S2 ~~> ... ~~> S1</span></span> would
|
|
create a circular definition. To change metaphor for a moment, it's as if, on
|
|
looking up <span class="extract"><span class="extract-syntax">S</span></span> in the index of a book, we found the entry "<span class="extract"><span class="extract-syntax">S</span></span>, see <span class="extract"><span class="extract-syntax">T</span></span>": we
|
|
then have to look up <span class="extract"><span class="extract-syntax">T</span></span> to find, say, "<span class="extract"><span class="extract-syntax">T</span></span>, 125", and turn to page 125. It
|
|
would be no good to find instead "<span class="extract"><span class="extract-syntax">T</span></span>, see <span class="extract"><span class="extract-syntax">S</span></span>".
|
|
</p>
|
|
|
|
<ul class="footnotetexts"><li class="footnote" id="fn:3"><p class="inwebfootnote"><sup id="fnref:3"><a href="#fn:3" rel="footnote">3</a></sup> There are fleeting exceptional cases when a symbol can be wired to another
|
|
symbol in the same package, but those occur only with sockets and plugs in the
|
|
special connectors package, and only temporarily even then.
|
|
<a href="#fnref:3" title="return to text"> ↩</a></p></li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>§7. </b>Special symbols called plugs and sockets are used to import or export meanings
|
|
from one tree of Inter code to a potential other tree, which will be "linked"
|
|
into it later on.
|
|
</p>
|
|
|
|
<p class="commentary">For example, <a href="../inform7/index.html" class="internal">inform7</a> compiles a tree of Inter, but then <a href="../inter/index.html" class="internal">inter</a> links
|
|
this with a separately compiled Inter tree from <a href="../BasicInformKit/index.html" class="internal">BasicInformKit</a>. Each both
|
|
imports from and exports to the other.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> ..................... .......................</span>
|
|
<span class="plain-syntax"> . </span><span class="element-syntax">Main</span><span class="plain-syntax"> </span><span class="element-syntax">tree</span><span class="plain-syntax"> . ~~~~~~~~> . </span><span class="element-syntax">BasicInformKit</span><span class="plain-syntax"> </span><span class="element-syntax">tree</span><span class="plain-syntax"> .</span>
|
|
<span class="plain-syntax"> . . . .</span>
|
|
<span class="plain-syntax"> . . <~~~~~~~~ . .</span>
|
|
<span class="plain-syntax"> ..................... .......................</span>
|
|
</pre>
|
|
<p class="commentary">It would be chaotic<sup id="fnref:4"><a href="#fn:4" rel="footnote">4</a></sup> to allow random symbols in packages all over each tree
|
|
to be wired directly to symbols in the other. Instead, every tree has a sort
|
|
of embassy package <span class="extract"><span class="extract-syntax">/main/connectors</span></span> (a package called <span class="extract"><span class="extract-syntax">connectors</span></span> which is
|
|
a subpackage of <span class="extract"><span class="extract-syntax">main</span></span>) which acts as an intermediary.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> ............................... ..................................</span>
|
|
<span class="plain-syntax"> . </span><span class="element-syntax">Main</span><span class="plain-syntax"> </span><span class="element-syntax">tree</span><span class="plain-syntax"> . . </span><span class="element-syntax">BasicInformKit</span><span class="plain-syntax"> </span><span class="element-syntax">tree</span><span class="plain-syntax"> .</span>
|
|
<span class="plain-syntax"> . +------------+ . . +------------+ .</span>
|
|
<span class="plain-syntax"> . </span><span class="element-syntax">other</span><span class="plain-syntax"> | </span><span class="element-syntax">connectors</span><span class="plain-syntax"> | . . | </span><span class="element-syntax">connectors</span><span class="plain-syntax"> | .</span>
|
|
<span class="plain-syntax"> . </span><span class="element-syntax">packages</span><span class="plain-syntax"> ~~~~~~~> </span><span class="element-syntax">plugs</span><span class="plain-syntax"> ~~~~~~~~~~~~~~> </span><span class="element-syntax">sockets</span><span class="plain-syntax"> ~~~~~> </span><span class="element-syntax">other</span><span class="plain-syntax"> .</span>
|
|
<span class="plain-syntax"> . <~~~~ </span><span class="element-syntax">sockets</span><span class="plain-syntax"> <~~~~~~~~~~~~~~ </span><span class="element-syntax">plugs</span><span class="plain-syntax"> <~~~~~~~~~ </span><span class="element-syntax">packages</span><span class="plain-syntax"> .</span>
|
|
<span class="plain-syntax"> . +------------+ . . +------------+ .</span>
|
|
<span class="plain-syntax"> ............................... ..................................</span>
|
|
</pre>
|
|
<p class="commentary">The connectors package contains only symbols, and they are all either "plugs" or
|
|
"sockets". A "plug" is made for every external meaning needed by a tree; a
|
|
"socket" is made for each meaning that the tree declares itself but wants to
|
|
make available for other trees to access. So if you know the contents of the
|
|
connectors package of a tree, you know everything it needs from outside (plugs)
|
|
and everything it offers to the outside (sockets).
|
|
</p>
|
|
|
|
<p class="commentary">For further zany ASCII-art like this, see <a href="2-tw2.html" class="internal">The Wiring</a>.
|
|
</p>
|
|
|
|
<ul class="footnotetexts"><li class="footnote" id="fn:4"><p class="inwebfootnote"><sup id="fnref:4"><a href="#fn:4" rel="footnote">4</a></sup> And also slow, and prone to namespace collisions.
|
|
<a href="#fnref:4" title="return to text"> ↩</a></p></li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>§8. </b>It is not literally the case that plugs in one tree are wired to sockets in
|
|
another, as the diagram above suggests. The actual wiring-together occurs only
|
|
when (part of) one tree is merged into another, in what is called <a href="2-trn.html" class="internal">Transmigration</a>.
|
|
</p>
|
|
|
|
<p class="commentary">Transmigration is by definition the process of moving a package from one tree
|
|
to another. Almost the whole design of Inter is motivated by the need to make this
|
|
fast — the hierarchies of packages, the use of wiring, and the existence of sockets
|
|
and plugs all came about working backwards from the goal of implementing
|
|
transmigration efficiently.
|
|
</p>
|
|
|
|
<p class="commentary">Transmigration is how the <a href="../pipeline-module/index.html" class="internal">pipeline</a> for processing Inter links a tree
|
|
produced by <a href="../inform7/index.html" class="internal">inform7</a> to trees from kits produced by <a href="../inter/index.html" class="internal">inter</a>. This
|
|
diagram is also a little simplified, but the idea is right. We start with:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> ......................... .........................</span>
|
|
<span class="plain-syntax"> . </span><span class="element-syntax">Main</span><span class="plain-syntax"> </span><span class="element-syntax">tree</span><span class="plain-syntax"> . . </span><span class="element-syntax">BasicInformKit</span><span class="plain-syntax"> </span><span class="element-syntax">tree</span><span class="plain-syntax"> .</span>
|
|
<span class="plain-syntax"> . </span><span class="element-syntax">main</span><span class="plain-syntax"> . . </span><span class="element-syntax">main</span><span class="plain-syntax"> .</span>
|
|
<span class="plain-syntax"> . </span><span class="element-syntax">architectural</span><span class="plain-syntax"> . . </span><span class="element-syntax">architectural</span><span class="plain-syntax"> .</span>
|
|
<span class="plain-syntax"> . </span><span class="element-syntax">basic_inform</span><span class="plain-syntax"> . . </span><span class="element-syntax">BasicInformKit</span><span class="plain-syntax"> .</span>
|
|
<span class="plain-syntax"> . </span><span class="element-syntax">source_text</span><span class="plain-syntax"> . . </span><span class="element-syntax">connectors</span><span class="plain-syntax"> .</span>
|
|
<span class="plain-syntax"> . </span><span class="element-syntax">connectors</span><span class="plain-syntax"> . . .</span>
|
|
<span class="plain-syntax"> ......................... .........................</span>
|
|
</pre>
|
|
<p class="commentary">where all of the substantive content of the BasicInformKit tree is in its
|
|
package <span class="extract"><span class="extract-syntax">/main/BasicInformKit</span></span>. Transmigration simply moves that package,
|
|
the result being:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> ......................... .........................</span>
|
|
<span class="plain-syntax"> . Main tree . . BasicInformKit tree .</span>
|
|
<span class="plain-syntax"> . main . . main .</span>
|
|
<span class="plain-syntax"> . architectural . . architectural .</span>
|
|
<span class="plain-syntax"> . basic_inform . . connectors .</span>
|
|
<span class="plain-syntax"> . source_text . . .</span>
|
|
<span class="plain-syntax"> . BasicInformKit . . .</span>
|
|
<span class="plain-syntax"> . connectors . . .</span>
|
|
<span class="plain-syntax"> ......................... .........................</span>
|
|
</pre>
|
|
<p class="commentary">The original BasicInformKit tree is reduced to a husk and can be discarded.
|
|
</p>
|
|
|
|
<p class="commentary">Plugs and sockets are important here because when BasicInformKit moves to the
|
|
main tree, its plugs looking for meanings in that tree can now be connected
|
|
to sockets in it; and conversely, plugs in the main tree hoping to connect
|
|
to meanings in BasicInformKit can now connect to the relevant sockets.
|
|
</p>
|
|
|
|
<p class="commentary">There are conventions on what goes in the <span class="extract"><span class="extract-syntax">main</span></span> package of each tree: see
|
|
<a href="../building-module/1-ls.html" class="internal">Large-Scale Structure (in building)</a> for more on that. (The <span class="extract"><span class="extract-syntax">architectural</span></span>
|
|
package in each tree just makes some definitions establishing the size of
|
|
integers, and so on, and for these two trees whose definitions will just be
|
|
duplicates of each other.)
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP9" class="paragraph-anchor"></a><b>§9. The warehouse and the building site. </b>There is a lot of memory to be managed here: Inter trees can be huge, though
|
|
there are never more than one or two in memory at once.
|
|
</p>
|
|
|
|
<p class="commentary">In particular, each <a href="2-it.html#SP1" class="internal">inter_tree</a> structure contains two pools of data
|
|
besides the actual tree:<sup id="fnref:5"><a href="#fn:5" rel="footnote">5</a></sup>
|
|
</p>
|
|
|
|
<ul class="items"><li>(a) A "building site", which contains workspace data needed by the <a href="../building-module/index.html" class="internal">building</a>
|
|
module. <a href="../building-module/index.html" class="internal">building</a> is essentially a piece of middleware sitting on top of
|
|
this one, and making it easier for the compilers to use our facilities. We
|
|
will ignore the building site completely here: it's not our problem.
|
|
</li><li>(b) A "warehouse", which very much is our problem: see <a href="2-tw.html" class="internal">The Warehouse</a>.
|
|
This provides storage for strings, symbols tables and the like, assigning each
|
|
one an ID number. Resource number 178, for example, might be a <span class="extract"><span class="extract-syntax">text_stream</span></span>
|
|
which is the content of some text literal in a function, while 179 might be
|
|
an <a href="2-st.html#SP1" class="internal">inter_symbols_table</a> belonging to some package.
|
|
</li></ul>
|
|
<ul class="footnotetexts"><li class="footnote" id="fn:5"><p class="inwebfootnote"><sup id="fnref:5"><a href="#fn:5" rel="footnote">5</a></sup> In real-life botany, trees do not have building sites or warehouses, but
|
|
mixing some metaphors cannot really be helped. Trees in nature do not grow
|
|
the way they do in computer science.
|
|
<a href="#fnref:5" title="return to text"> ↩</a></p></li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP10" class="paragraph-anchor"></a><b>§10. Nodes and instructions. </b>Each node in an Inter tree represents a single Inter instruction,<sup id="fnref:6"><a href="#fn:6" rel="footnote">6</a></sup> details of
|
|
which are stored as a stretch of bytecode in memory.
|
|
</p>
|
|
|
|
<p class="commentary">This use of both a tree and also a mass of binary bytecode is an attempt to
|
|
have our cake and eat it. The tree structure makes it quick and easy to splice,
|
|
cut and reorder code; the binary bytecode storage is quick to load from a file.
|
|
Still, the result is an unusual hybrid of a data structure.
|
|
</p>
|
|
|
|
<p class="commentary">For example, the tree might start out like this:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> ... </span><span class="constant-syntax">102</span><span class="plain-syntax"> </span><span class="constant-syntax">103</span><span class="plain-syntax"> </span><span class="constant-syntax">104</span><span class="plain-syntax"> </span><span class="constant-syntax">105</span><span class="plain-syntax"> </span><span class="constant-syntax">106</span><span class="plain-syntax"> </span><span class="constant-syntax">107</span><span class="plain-syntax"> </span><span class="constant-syntax">108</span><span class="plain-syntax"> </span><span class="constant-syntax">109</span><span class="plain-syntax"> ...</span>
|
|
<span class="plain-syntax"> </span><span class="element-syntax">node1</span><span class="plain-syntax"> -----------------------> [.........]</span>
|
|
<span class="plain-syntax"> </span><span class="element-syntax">node2</span><span class="plain-syntax"> -------------------------------> [.....]</span>
|
|
<span class="plain-syntax"> </span><span class="element-syntax">node3</span><span class="plain-syntax"> ---------------------------------------> [.........]</span>
|
|
</pre>
|
|
<p class="commentary">Here <span class="extract"><span class="extract-syntax">node1</span></span> represents an instruction, with the details stored at bytecode
|
|
locations 103 to 105; <span class="extract"><span class="extract-syntax">node2</span></span> points to bytecode at 106 to 107, and so on.
|
|
But then we could decide, when optimising code, that we want instructions
|
|
<span class="extract"><span class="extract-syntax">node2</span></span> and <span class="extract"><span class="extract-syntax">node3</span></span> performed the other way round. Simple amendments to
|
|
the tree structure achieve this without needing to edit the bytecode:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> ... </span><span class="constant-syntax">102</span><span class="plain-syntax"> </span><span class="constant-syntax">103</span><span class="plain-syntax"> </span><span class="constant-syntax">104</span><span class="plain-syntax"> </span><span class="constant-syntax">105</span><span class="plain-syntax"> </span><span class="constant-syntax">106</span><span class="plain-syntax"> </span><span class="constant-syntax">107</span><span class="plain-syntax"> </span><span class="constant-syntax">108</span><span class="plain-syntax"> </span><span class="constant-syntax">109</span><span class="plain-syntax"> ...</span>
|
|
<span class="plain-syntax"> </span><span class="element-syntax">node1</span><span class="plain-syntax"> -----------------------> [.........]</span>
|
|
<span class="plain-syntax"> </span><span class="element-syntax">node3</span><span class="plain-syntax"> ---------------------------------------> [.........]</span>
|
|
<span class="plain-syntax"> </span><span class="element-syntax">node2</span><span class="plain-syntax"> -------------------------------> [.....]</span>
|
|
</pre>
|
|
<p class="commentary">Indeed, we could decide that the instruction at <span class="extract"><span class="extract-syntax">node2</span></span> is redundant and cut it:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> ... 102 103 104 105 106 107 108 109 ...</span>
|
|
<span class="plain-syntax"> node1 -----------------------> [.........]</span>
|
|
<span class="plain-syntax"> node3 ---------------------------------------> [.........]</span>
|
|
</pre>
|
|
<p class="commentary">It doesn't matter that the resulting bytecode storage is all mixed up in
|
|
sequencing; the tree is what gives us the sequence of instructions, and the
|
|
order of words in bytecode memory is only significant within a single
|
|
instruction.
|
|
</p>
|
|
|
|
<ul class="footnotetexts"><li class="footnote" id="fn:6"><p class="inwebfootnote"><sup id="fnref:6"><a href="#fn:6" rel="footnote">6</a></sup> Well, except for the root node, which has no real meaning. But there is
|
|
only one of those.
|
|
<a href="#fnref:6" title="return to text"> ↩</a></p></li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP11" class="paragraph-anchor"></a><b>§11. </b>As these diagrams suggest, we can generate Inter instructions quite flexibly,
|
|
and are under no obligation to do so in sequence or all at once. (Indeed, we
|
|
can add entirely new instructions in the linking process or when optimising
|
|
code.)
|
|
</p>
|
|
|
|
<p class="commentary">So it is very useful to have a way to keep "bookmarks" in the tree, as positions
|
|
where we are currently writing code, and might want to return to. For this
|
|
purpose, we have the <a href="2-bkm.html#SP1" class="internal">inter_bookmark</a> type, which can represent any feasible
|
|
write position in the tree. (This is not the same thing as representing any
|
|
existing node in the tree: see <a href="2-bkm.html" class="internal">Bookmarks</a> for more.)
|
|
</p>
|
|
|
|
<p class="commentary">And this in turn allows for a simple API for <a href="2-np.html" class="internal">Node Placement</a>, allowing us
|
|
to move or remove nodes in the tree, and to keep track of cursor-like moving
|
|
bookmark positions when we generate a stream of new nodes and place them one
|
|
after another.
|
|
</p>
|
|
|
|
<nav role="progress"><div class="progresscontainer">
|
|
<ul class="progressbar"><li class="progressprevoff">❮</li><li class="progresscurrentchapter">P</li><li class="progresscurrent">wtmd</li><li class="progresschapter"><a href="1-bm.html">1</a></li><li class="progresschapter"><a href="2-it.html">2</a></li><li class="progresschapter"><a href="3-ic.html">3</a></li><li class="progresschapter"><a href="4-tac.html">4</a></li><li class="progresschapter"><a href="5-tac.html">5</a></li><li class="progresschapter"><a href="6-tpc.html">6</a></li><li class="progressnext"><a href="1-bm.html">❯</a></li></ul></div>
|
|
</nav><!--End of weave-->
|
|
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|