Ports-and-Packets.html 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
  2. <html>
  3. <!-- Created on December 10, 2012 by texi2html 1.82
  4. texi2html was written by:
  5. Lionel Cons <[email protected]> (original author)
  6. Karl Berry <[email protected]>
  7. Olaf Bachmann <[email protected]>
  8. and many others.
  9. Maintained by: Many creative people.
  10. Send bugs and suggestions to <[email protected]>
  11. -->
  12. <head>
  13. <title>avram - a virtual machine code interpreter: 3.8.2 Ports and Packets</title>
  14. <meta name="description" content="avram - a virtual machine code interpreter: 3.8.2 Ports and Packets">
  15. <meta name="keywords" content="avram - a virtual machine code interpreter: 3.8.2 Ports and Packets">
  16. <meta name="resource-type" content="document">
  17. <meta name="distribution" content="global">
  18. <meta name="Generator" content="texi2html 1.82">
  19. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  20. <style type="text/css">
  21. <!--
  22. a.summary-letter {text-decoration: none}
  23. blockquote.smallquotation {font-size: smaller}
  24. pre.display {font-family: serif}
  25. pre.format {font-family: serif}
  26. pre.menu-comment {font-family: serif}
  27. pre.menu-preformatted {font-family: serif}
  28. pre.smalldisplay {font-family: serif; font-size: smaller}
  29. pre.smallexample {font-size: smaller}
  30. pre.smallformat {font-family: serif; font-size: smaller}
  31. pre.smalllisp {font-size: smaller}
  32. span.roman {font-family:serif; font-weight:normal;}
  33. span.sansserif {font-family:sans-serif; font-weight:normal;}
  34. ul.toc {list-style: none}
  35. -->
  36. </style>
  37. </head>
  38. <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  39. <a name="Ports-and-Packets"></a>
  40. <table cellpadding="1" cellspacing="1" border="0">
  41. <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"> &lt; </a>]</td>
  42. <td valign="middle" align="left">[<a href="Instruction-Stacks.html#Instruction-Stacks" title="Next section in reading order"> &gt; </a>]</td>
  43. <td valign="middle" align="left"> &nbsp; </td>
  44. <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  45. <td valign="middle" align="left">[<a href="Emulation-Primitives.html#Emulation-Primitives" title="Up section"> Up </a>]</td>
  46. <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
  47. <td valign="middle" align="left"> &nbsp; </td>
  48. <td valign="middle" align="left"> &nbsp; </td>
  49. <td valign="middle" align="left"> &nbsp; </td>
  50. <td valign="middle" align="left"> &nbsp; </td>
  51. <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
  52. <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  53. <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
  54. <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  55. </tr></table>
  56. <hr size="1">
  57. <a name="Ports-and-Packets-1"></a>
  58. <h3 class="subsection">3.8.2 Ports and Packets</h3>
  59. <p>A pointer type declared as a <code>port</code> points to a structure in the
  60. following form, where a <code>flag</code> is an unsigned short integer type,
  61. and a <code>counter</code> is an unsigned long integer.
  62. <a name="index-counter-1"></a>
  63. <a name="index-flag"></a>
  64. <a name="index-avm_005fpacket"></a>
  65. </p>
  66. <table><tr><td>&nbsp;</td><td><pre class="example">struct avm_packet
  67. {
  68. port parent;
  69. counter errors;
  70. portal descendents;
  71. list impetus, contents;
  72. flag predicating;
  73. };
  74. </pre></td></tr></table>
  75. <p>For reasons that make sense to C, the <code>avm_packet</code> and <code>port</code>
  76. types are declared in <code>lists.h</code>, but a few memory management
  77. operations on them are available by way of functions declared in
  78. &lsquo;<tt>ports.h</tt>&rsquo;. The intended meaning of this structure is described
  79. presently, but first the memory management functions are as follows.
  80. </p>
  81. <dl>
  82. <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>
  83. <dd><p>This function attempts to allocate storage for a new packet structure
  84. and returns its address if successful. If storage can not be allocated,
  85. a <code>NULL</code> pointer is returned. The <code>errors</code>, <code>parent</code>, and
  86. <code>predicating</code> fields are initialized with the parameters supplied
  87. by the caller. The rest of the structure is filled with zeros. A local
  88. memory cache is used for improved performance.
  89. </p></dd></dl>
  90. <dl>
  91. <dt><a name="index-avm_005fsever"></a><u>Function:</u> void <b>avm_sever</b><i> (port <var>appendage</var>)</i></dt>
  92. <dd><p>This function reclaims the storage associated with a <code>port</code>, either
  93. freeing it entirely or holding it in a local cache. None of the
  94. entities that may be referenced by pointers within the structure are
  95. affected. Only this function should be used by client programs for
  96. disposing of ports, not the <code>free</code> function directly, or some
  97. internal bookkeeping will be disrupted. An internal error results if the
  98. argument is a <code>NULL</code> pointer.
  99. </p></dd></dl>
  100. <dl>
  101. <dt><a name="index-avm_005finitialize_005fports"></a><u>Function:</u> void <b>avm_initialize_ports</b><i> ()</i></dt>
  102. <dd><p>This function must be called prior to calling either of the two above,
  103. in order to initialize some static variables.
  104. </p></dd></dl>
  105. <dl>
  106. <dt><a name="index-avm_005fcount_005fports"></a><u>Function:</u> void <b>avm_count_ports</b><i> ()</i></dt>
  107. <dd><p>This function may be called after the last call to any of the other
  108. functions in this section in order to detect and report unreclaimed
  109. storage associated with ports. A non-fatal warning will be written to
  110. standard error if any is detected, but otherwise there is no effect.
  111. </p></dd></dl>
  112. <p>The interesting aspect of this data structure is the role it plays in
  113. capturing the state of a computation. For this purpose, it corresponds
  114. to a single node in a partially computed result to be represented by a
  115. <code>list</code> when it&rsquo;s finished. The nodes should be envisioned as a
  116. doubly-linked binary tree, except that the pair of <code>descendents</code>
  117. for each node is not yet known with certainty, so a list of alternatives
  118. must be maintained.
  119. </p>
  120. <p>Because the computation is not completed while this data structure
  121. exists, there are always some empty fields in it. For example, the
  122. <code>descendents</code> and the <code>contents</code> fields embody the same
  123. information, the latter doing so in a compact as opposed to a more
  124. expanded form. Hence, it would be redundant for both fields to be
  125. non-empty at the same time. The data structure is built initially with
  126. <code>descendents</code> and no <code>contents</code>, only to be transformed into
  127. one with <code>contents</code> and no <code>descendents</code>.
  128. </p>
  129. <p>The significance of each field in the structure can be summarized as
  130. follows.
  131. </p>
  132. <dl compact="compact">
  133. <dt> <code>contents</code></dt>
  134. <dd><p>If the computational result destined for the <code>port</code> pointing to this packet
  135. is not complete, then this field is <code>NULL</code> and the
  136. <code>descendents</code> are being computed. Otherwise, it contains the result
  137. of the computation.
  138. </p></dd>
  139. <dt> <code>descendents</code></dt>
  140. <dd><p>This field points to a list of pairs of ports serving as the
  141. destinations for an ensemble of concurrent computations.<a name="DOCF3" href="avram_fot.html#FOOT3">(3)</a> The <code>head</code>
  142. and <code>tail</code> of the <code>contents</code> are to be identified respectively
  143. with the <code>contents</code> of the <code>left</code> and <code>right</code> <code>port</code>
  144. in the first pair to finish being computed.
  145. </p></dd>
  146. <dt> <code>parent</code></dt>
  147. <dd><p>If this packet is addressed by the <code>left</code> or the <code>right</code> of
  148. <code>port</code> in one of the <code>descendents</code> of some other packet, then
  149. this field points to that packet.
  150. </p></dd>
  151. <dt> <code>errors</code></dt>
  152. <dd><p>A non-zero value in this field indicates that the result destined for
  153. the <code>contents</code> of this packet is expected to be an error
  154. message. If the exact level of error severity incurred in the
  155. computation of the <code>contents</code> matches this number, then the
  156. contents can be assigned the result, but otherwise the result should
  157. propagate to the <code>contents</code> of the <code>parent</code>.
  158. </p></dd>
  159. <dt> <code>predicating</code></dt>
  160. <dd><p>A non-zero value in this field implies that the result destined for the
  161. <code>contents</code> of this packet is being computed in order to decide
  162. which arm of a conditional function should be chosen. I.e., a
  163. <code>NULL</code> result calls for the one that is invoked when the predicate
  164. is false.
  165. </p></dd>
  166. <dt> <code>impetus</code></dt>
  167. <dd><p>If the result destined for the <code>contents</code> of this packet is being
  168. computed in order to transform a virtual code fragment from its original
  169. form to an equivalent representation capable of being evaluated more
  170. directly, this field points to a <code>list</code> node at the root of the
  171. virtual code in its original form.
  172. </p></dd>
  173. </dl>
  174. <p>One of the hitherto undocumented fields in a <code>list</code> node structure
  175. <a name="index-interpretation"></a>
  176. <a name="index-impetus"></a>
  177. declared in &lsquo;<tt>lists.h</tt>&rsquo; is called the <code>interpretation</code>, and is
  178. of type <code>list</code>. A client program delving into sufficient depth of
  179. detail to be concerned with ports and packets may reasonably assign the
  180. <code>interpretation</code> field of the <code>list</code> referenced by the
  181. <code>impetus</code> field in a packet to be a copy of the <code>contents</code> of
  182. the packet when they are eventually obtained. Doing so will save some
  183. time by eliminating the need for it to be recomputed if the same virtual
  184. code should be executed again.
  185. </p>
  186. <p>If this course is taken, the <code>facilitator</code> field in a <code>list</code>
  187. <a name="index-facilitator"></a>
  188. node, also hitherto undocumented, should contain the address of the
  189. packet referring to the list node as its <code>impetus</code>. The reason for
  190. this additional link is so that it can be followed when the
  191. <code>impetus</code> of the packet is be cleared by <code>avm_dispose</code> in the
  192. event that the <code>list</code> node is freed before the computation
  193. completes. This action is performed in order to preclude a dangling
  194. pointer in the <code>impetus</code> field.
  195. </p>
  196. <hr size="1">
  197. <table cellpadding="1" cellspacing="1" border="0">
  198. <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"> &lt; </a>]</td>
  199. <td valign="middle" align="left">[<a href="Instruction-Stacks.html#Instruction-Stacks" title="Next section in reading order"> &gt; </a>]</td>
  200. <td valign="middle" align="left"> &nbsp; </td>
  201. <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  202. <td valign="middle" align="left">[<a href="Emulation-Primitives.html#Emulation-Primitives" title="Up section"> Up </a>]</td>
  203. <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
  204. <td valign="middle" align="left"> &nbsp; </td>
  205. <td valign="middle" align="left"> &nbsp; </td>
  206. <td valign="middle" align="left"> &nbsp; </td>
  207. <td valign="middle" align="left"> &nbsp; </td>
  208. <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
  209. <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  210. <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
  211. <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  212. </tr></table>
  213. <p>
  214. <font size="-1">
  215. This document was generated on <i>December 10, 2012</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.82</i></a>.
  216. </font>
  217. <br>
  218. </p>
  219. </body>
  220. </html>