123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230 |
- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
- <html>
- <!-- Created on December 10, 2012 by texi2html 1.82
- texi2html was written by:
- Lionel Cons <[email protected]> (original author)
- Karl Berry <[email protected]>
- Olaf Bachmann <[email protected]>
- and many others.
- Maintained by: Many creative people.
- Send bugs and suggestions to <[email protected]>
- -->
- <head>
- <title>avram - a virtual machine code interpreter: 3.8.2 Ports and Packets</title>
- <meta name="description" content="avram - a virtual machine code interpreter: 3.8.2 Ports and Packets">
- <meta name="keywords" content="avram - a virtual machine code interpreter: 3.8.2 Ports and Packets">
- <meta name="resource-type" content="document">
- <meta name="distribution" content="global">
- <meta name="Generator" content="texi2html 1.82">
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <style type="text/css">
- <!--
- a.summary-letter {text-decoration: none}
- blockquote.smallquotation {font-size: smaller}
- pre.display {font-family: serif}
- pre.format {font-family: serif}
- pre.menu-comment {font-family: serif}
- pre.menu-preformatted {font-family: serif}
- pre.smalldisplay {font-family: serif; font-size: smaller}
- pre.smallexample {font-size: smaller}
- pre.smallformat {font-family: serif; font-size: smaller}
- pre.smalllisp {font-size: smaller}
- span.roman {font-family:serif; font-weight:normal;}
- span.sansserif {font-family:sans-serif; font-weight:normal;}
- ul.toc {list-style: none}
- -->
- </style>
- </head>
- <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
- <a name="Ports-and-Packets"></a>
- <table cellpadding="1" cellspacing="1" border="0">
- <tr><td valign="middle" align="left">[<a href="Lists-of-Pairs-of-Ports.html#Lists-of-Pairs-of-Ports" title="Previous section in reading order"> < </a>]</td>
- <td valign="middle" align="left">[<a href="Instruction-Stacks.html#Instruction-Stacks" title="Next section in reading order"> > </a>]</td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> << </a>]</td>
- <td valign="middle" align="left">[<a href="Emulation-Primitives.html#Emulation-Primitives" title="Up section"> Up </a>]</td>
- <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> >> </a>]</td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
- <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
- <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
- <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
- </tr></table>
- <hr size="1">
- <a name="Ports-and-Packets-1"></a>
- <h3 class="subsection">3.8.2 Ports and Packets</h3>
- <p>A pointer type declared as a <code>port</code> points to a structure in the
- following form, where a <code>flag</code> is an unsigned short integer type,
- and a <code>counter</code> is an unsigned long integer.
- <a name="index-counter-1"></a>
- <a name="index-flag"></a>
- <a name="index-avm_005fpacket"></a>
- </p>
- <table><tr><td> </td><td><pre class="example">struct avm_packet
- {
- port parent;
- counter errors;
- portal descendents;
- list impetus, contents;
- flag predicating;
- };
- </pre></td></tr></table>
- <p>For reasons that make sense to C, the <code>avm_packet</code> and <code>port</code>
- types are declared in <code>lists.h</code>, but a few memory management
- operations on them are available by way of functions declared in
- ‘<tt>ports.h</tt>’. The intended meaning of this structure is described
- presently, but first the memory management functions are as follows.
- </p>
- <dl>
- <dt><a name="index-avm_005fnewport"></a><u>Function:</u> port <b>avm_newport</b><i> (counter <var>errors</var>, port <var>parent</var>, int <var>predicating</var>)</i></dt>
- <dd><p>This function attempts to allocate storage for a new packet structure
- and returns its address if successful. If storage can not be allocated,
- a <code>NULL</code> pointer is returned. The <code>errors</code>, <code>parent</code>, and
- <code>predicating</code> fields are initialized with the parameters supplied
- by the caller. The rest of the structure is filled with zeros. A local
- memory cache is used for improved performance.
- </p></dd></dl>
- <dl>
- <dt><a name="index-avm_005fsever"></a><u>Function:</u> void <b>avm_sever</b><i> (port <var>appendage</var>)</i></dt>
- <dd><p>This function reclaims the storage associated with a <code>port</code>, either
- freeing it entirely or holding it in a local cache. None of the
- entities that may be referenced by pointers within the structure are
- affected. Only this function should be used by client programs for
- disposing of ports, not the <code>free</code> function directly, or some
- internal bookkeeping will be disrupted. An internal error results if the
- argument is a <code>NULL</code> pointer.
- </p></dd></dl>
- <dl>
- <dt><a name="index-avm_005finitialize_005fports"></a><u>Function:</u> void <b>avm_initialize_ports</b><i> ()</i></dt>
- <dd><p>This function must be called prior to calling either of the two above,
- in order to initialize some static variables.
- </p></dd></dl>
- <dl>
- <dt><a name="index-avm_005fcount_005fports"></a><u>Function:</u> void <b>avm_count_ports</b><i> ()</i></dt>
- <dd><p>This function may be called after the last call to any of the other
- functions in this section in order to detect and report unreclaimed
- storage associated with ports. A non-fatal warning will be written to
- standard error if any is detected, but otherwise there is no effect.
- </p></dd></dl>
- <p>The interesting aspect of this data structure is the role it plays in
- capturing the state of a computation. For this purpose, it corresponds
- to a single node in a partially computed result to be represented by a
- <code>list</code> when it’s finished. The nodes should be envisioned as a
- doubly-linked binary tree, except that the pair of <code>descendents</code>
- for each node is not yet known with certainty, so a list of alternatives
- must be maintained.
- </p>
- <p>Because the computation is not completed while this data structure
- exists, there are always some empty fields in it. For example, the
- <code>descendents</code> and the <code>contents</code> fields embody the same
- information, the latter doing so in a compact as opposed to a more
- expanded form. Hence, it would be redundant for both fields to be
- non-empty at the same time. The data structure is built initially with
- <code>descendents</code> and no <code>contents</code>, only to be transformed into
- one with <code>contents</code> and no <code>descendents</code>.
- </p>
- <p>The significance of each field in the structure can be summarized as
- follows.
- </p>
- <dl compact="compact">
- <dt> <code>contents</code></dt>
- <dd><p>If the computational result destined for the <code>port</code> pointing to this packet
- is not complete, then this field is <code>NULL</code> and the
- <code>descendents</code> are being computed. Otherwise, it contains the result
- of the computation.
- </p></dd>
- <dt> <code>descendents</code></dt>
- <dd><p>This field points to a list of pairs of ports serving as the
- destinations for an ensemble of concurrent computations.<a name="DOCF3" href="avram_fot.html#FOOT3">(3)</a> The <code>head</code>
- and <code>tail</code> of the <code>contents</code> are to be identified respectively
- with the <code>contents</code> of the <code>left</code> and <code>right</code> <code>port</code>
- in the first pair to finish being computed.
- </p></dd>
- <dt> <code>parent</code></dt>
- <dd><p>If this packet is addressed by the <code>left</code> or the <code>right</code> of
- <code>port</code> in one of the <code>descendents</code> of some other packet, then
- this field points to that packet.
- </p></dd>
- <dt> <code>errors</code></dt>
- <dd><p>A non-zero value in this field indicates that the result destined for
- the <code>contents</code> of this packet is expected to be an error
- message. If the exact level of error severity incurred in the
- computation of the <code>contents</code> matches this number, then the
- contents can be assigned the result, but otherwise the result should
- propagate to the <code>contents</code> of the <code>parent</code>.
- </p></dd>
- <dt> <code>predicating</code></dt>
- <dd><p>A non-zero value in this field implies that the result destined for the
- <code>contents</code> of this packet is being computed in order to decide
- which arm of a conditional function should be chosen. I.e., a
- <code>NULL</code> result calls for the one that is invoked when the predicate
- is false.
- </p></dd>
- <dt> <code>impetus</code></dt>
- <dd><p>If the result destined for the <code>contents</code> of this packet is being
- computed in order to transform a virtual code fragment from its original
- form to an equivalent representation capable of being evaluated more
- directly, this field points to a <code>list</code> node at the root of the
- virtual code in its original form.
- </p></dd>
- </dl>
- <p>One of the hitherto undocumented fields in a <code>list</code> node structure
- <a name="index-interpretation"></a>
- <a name="index-impetus"></a>
- declared in ‘<tt>lists.h</tt>’ is called the <code>interpretation</code>, and is
- of type <code>list</code>. A client program delving into sufficient depth of
- detail to be concerned with ports and packets may reasonably assign the
- <code>interpretation</code> field of the <code>list</code> referenced by the
- <code>impetus</code> field in a packet to be a copy of the <code>contents</code> of
- the packet when they are eventually obtained. Doing so will save some
- time by eliminating the need for it to be recomputed if the same virtual
- code should be executed again.
- </p>
- <p>If this course is taken, the <code>facilitator</code> field in a <code>list</code>
- <a name="index-facilitator"></a>
- node, also hitherto undocumented, should contain the address of the
- packet referring to the list node as its <code>impetus</code>. The reason for
- this additional link is so that it can be followed when the
- <code>impetus</code> of the packet is be cleared by <code>avm_dispose</code> in the
- event that the <code>list</code> node is freed before the computation
- completes. This action is performed in order to preclude a dangling
- pointer in the <code>impetus</code> field.
- </p>
- <hr size="1">
- <table cellpadding="1" cellspacing="1" border="0">
- <tr><td valign="middle" align="left">[<a href="Lists-of-Pairs-of-Ports.html#Lists-of-Pairs-of-Ports" title="Previous section in reading order"> < </a>]</td>
- <td valign="middle" align="left">[<a href="Instruction-Stacks.html#Instruction-Stacks" title="Next section in reading order"> > </a>]</td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> << </a>]</td>
- <td valign="middle" align="left">[<a href="Emulation-Primitives.html#Emulation-Primitives" title="Up section"> Up </a>]</td>
- <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> >> </a>]</td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left"> </td>
- <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
- <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
- <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
- <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
- </tr></table>
- <p>
- <font size="-1">
- This document was generated on <i>December 10, 2012</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.82</i></a>.
- </font>
- <br>
- </p>
- </body>
- </html>
|