ifhub/inform7
1
0
Fork 0
mirror of https://github.com/ganelson/inform.git synced 2024-07-08 18:14:21 +03:00
Code Issues Projects Releases Wiki Activity
inform7/docs/bytecode-module/P-wtmd.html
Graham Nelson 9ff95ee1dc Beginning to make kind-checking optional in Inter
2022-02-14 23:45:34 +00:00

472 lines
42 KiB
HTML
Raw Blame History

<!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">&#167;1. Prerequisites</a></li><li><a href="P-wtmd.html#SP2">&#167;2. What is intermediate about inter</a></li><li><a href="P-wtmd.html#SP4">&#167;4. Packages</a></li><li><a href="P-wtmd.html#SP5">&#167;5. Symbols</a></li><li><a href="P-wtmd.html#SP9">&#167;9. The warehouse and the building site</a></li><li><a href="P-wtmd.html#SP10">&#167;10. Nodes and instructions</a></li></ul><hr class="tocbar">
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>&#167;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>&#167;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 &mdash; perhaps Inform 7 source text,
perhaps Inform 6-syntax source for a kit &mdash; 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"> ----&gt; </span><span class="function-syntax">AST</span><span class="plain-syntax"> ------------&gt; </span><span class="function-syntax">IR</span><span class="plain-syntax"> ----&gt; </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>&#9679; 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>&#9679; 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 &mdash; 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"> ---&gt; </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"> ----&gt; </span><span class="element-syntax">Inter</span><span class="plain-syntax"> ----&gt; </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"> ---&gt; </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"> &#x21A9;</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"> &#x21A9;</a></p></li></ul>
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>&#167;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>&#167;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>&#167;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 &mdash; a variable, say, or a function &mdash; 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>&#167;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 ~~&gt; 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"> ~~~~~~~~~~~~~~~~~~~~&gt; </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 ~~&gt; T</span></span> very definitely does not mean that <span class="extract"><span class="extract-syntax">T ~~&gt; S</span></span>,
and indeed circuits are forbidden, because <span class="extract"><span class="extract-syntax">S1 ~~&gt; S2 ~~&gt; ... ~~&gt; 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"> &#x21A9;</a></p></li></ul>
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>&#167;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"> . ~~~~~~~~&gt; . </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"> . . &lt;~~~~~~~~ . .</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"> ~~~~~~~&gt; </span><span class="element-syntax">plugs</span><span class="plain-syntax"> ~~~~~~~~~~~~~~&gt; </span><span class="element-syntax">sockets</span><span class="plain-syntax"> ~~~~~&gt; </span><span class="element-syntax">other</span><span class="plain-syntax"> .</span>
<span class="plain-syntax"> . &lt;~~~~ </span><span class="element-syntax">sockets</span><span class="plain-syntax"> &lt;~~~~~~~~~~~~~~ </span><span class="element-syntax">plugs</span><span class="plain-syntax"> &lt;~~~~~~~~~ </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"> &#x21A9;</a></p></li></ul>
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>&#167;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 &mdash; 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>&#167;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"> &#x21A9;</a></p></li></ul>
<p class="commentary firstcommentary"><a id="SP10" class="paragraph-anchor"></a><b>&#167;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"> -----------------------&gt; [.........]</span>
<span class="plain-syntax"> </span><span class="element-syntax">node2</span><span class="plain-syntax"> -------------------------------&gt; [.....]</span>
<span class="plain-syntax"> </span><span class="element-syntax">node3</span><span class="plain-syntax"> ---------------------------------------&gt; [.........]</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"> -----------------------&gt; [.........]</span>
<span class="plain-syntax"> </span><span class="element-syntax">node3</span><span class="plain-syntax"> ---------------------------------------&gt; [.........]</span>
<span class="plain-syntax"> </span><span class="element-syntax">node2</span><span class="plain-syntax"> -------------------------------&gt; [.....]</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 -----------------------&gt; [.........]</span>
<span class="plain-syntax"> node3 ---------------------------------------&gt; [.........]</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"> &#x21A9;</a></p></li></ul>
<p class="commentary firstcommentary"><a id="SP11" class="paragraph-anchor"></a><b>&#167;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">&#10094;</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-tnc.html">4</a></li><li class="progresschapter"><a href="5-tlc.html">5</a></li><li class="progresschapter"><a href="6-tpc.html">6</a></li><li class="progressnext"><a href="1-bm.html">&#10095;</a></li></ul></div>
</nav><!--End of weave-->
</main>
</body>
</html>
Reference in a new issue View git blame Copy permalink