engine.html (5626B)
1 <!DOCTYPE html> 2 <html> 3 <!-- Created by GNU Texinfo 7.0.2, https://www.gnu.org/software/texinfo/ --> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 6 <!-- Released 2023 under AGPL3 --> 7 <title>engine (vise)</title> 8 9 <meta name="description" content="engine (vise)"> 10 <meta name="keywords" content="engine (vise)"> 11 <meta name="resource-type" content="document"> 12 <meta name="distribution" content="global"> 13 <meta name="Generator" content="makeinfo"> 14 <meta name="viewport" content="width=device-width,initial-scale=1"> 15 16 <link href="index.html" rel="start" title="Top"> 17 <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 18 <link href="index.html" rel="up" title="Top"> 19 <link href="language.html" rel="next" title="language"> 20 <link href="render.html" rel="prev" title="render"> 21 <style type="text/css"> 22 <!-- 23 ul.mark-bullet {list-style-type: disc} 24 --> 25 </style> 26 27 28 </head> 29 30 <body lang="en"> 31 <div class="chapter-level-extent" id="engine"> 32 <div class="nav-panel"> 33 <p> 34 Next: <a href="language.html" accesskey="n" rel="next">Handling languages</a>, Previous: <a href="render.html" accesskey="p" rel="prev">Rendering</a>, Up: <a href="index.html" accesskey="u" rel="up">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> 35 </div> 36 <hr> 37 <h2 class="chapter" id="Using-vise">8 Using vise</h2> 38 39 <p>Implementers of <code class="code">vise</code> should interface with the system using the <code class="code">engine</code> module. 40 </p> 41 <p>The engine comes in two implementations, one volatile base implemetnation and a subclass that includes persistent state. 42 </p> 43 44 <ul class="mini-toc"> 45 <li><a href="#Modes-of-operation" accesskey="1">Modes of operation</a></li> 46 <li><a href="#Configuration" accesskey="2">Configuration</a></li> 47 <li><a href="#Sessions" accesskey="3">Sessions</a></li> 48 <li><a href="#Execution-context" accesskey="4">Execution context</a></li> 49 </ul> 50 <div class="section-level-extent" id="Modes-of-operation"> 51 <h3 class="section">8.1 Modes of operation</h3> 52 53 <p>The <code class="code">engine</code> module provides three different modes of operation for the engine implementations. 54 </p> 55 56 <ul class="mini-toc"> 57 <li><a href="#Manual-operation" accesskey="1">Manual operation</a></li> 58 <li><a href="#Synchronous-loop" accesskey="2">Synchronous loop</a></li> 59 <li><a href="#Asynchronous-one_002dshot" accesskey="3">Asynchronous one-shot</a></li> 60 </ul> 61 <div class="subsection-level-extent" id="Manual-operation"> 62 <h4 class="subsection">8.1.1 Manual operation</h4> 63 64 <p>Directly interaction with an <code class="code">engine.Engine</code> instance. 65 </p> 66 <p>The engine is manually initialized, and execution must be explicitly triggered with input every time the VM yields control. 67 </p> 68 <p>Output flushing must also be operated manually. 69 </p> 70 <p>The interface is the same for both persistent and volatile operation. 71 </p> 72 73 </div> 74 <div class="subsection-level-extent" id="Synchronous-loop"> 75 <h4 class="subsection">8.1.2 Synchronous loop</h4> 76 77 <p>Receives input from a reader and writes into to a writer, and executes the underlying <code class="code">engine.Engine</code> with given inputs until execution is terminated. 78 </p> 79 <p>The loop may be either persistent or volatile. 80 </p> 81 <p>This mode drives the interactive driver execution tool. 82 </p> 83 84 </div> 85 <div class="subsection-level-extent" id="Asynchronous-one_002dshot"> 86 <h4 class="subsection">8.1.3 Asynchronous one-shot</h4> 87 88 <p>Compatible with e.g. a network socket or HTTP frontend. The <code class="code">engine.RunPersisted</code> method restores a persisted state and runs one single input until VM yield after which the new state is persisted. 89 </p> 90 <p>This mode of operation can only be used with persistent state. 91 </p> 92 93 </div> 94 </div> 95 <div class="section-level-extent" id="Configuration"> 96 <h3 class="section">8.2 Configuration</h3> 97 98 <p>The engine configuration defines the top-level parameters for the execution environment, including maximum output size, default language, execution entry point and more. 99 </p> 100 <p>Please refer to <code class="code">engine.Config</code> for details. 101 </p> 102 103 </div> 104 <div class="section-level-extent" id="Sessions"> 105 <h3 class="section">8.3 Sessions</h3> 106 107 <p>The <code class="code">engine.Config.SessionId</code> is used to disambiguate the end-user that is interacting with the engine. 108 </p> 109 <p>For example, in a <abbr class="abbr">USSD</abbr> context, the <code class="code">SessionId</code> may be the <em class="emph">phone number</em> of the end-user. 110 </p> 111 112 <a class="anchor" id="execution_005fcontext"></a></div> 113 <div class="section-level-extent" id="Execution-context"> 114 <h3 class="section">8.4 Execution context</h3> 115 116 <p>The engine stores the <code class="code">SessionId</code> aswell as the current chosen <code class="code">lang.Language</code> in the execution context. This is passed through to the VM operation, and is available for client code, specifically: 117 </p> 118 <ul class="itemize mark-bullet"> 119 <li>When resolving symbols with <code class="code">LOAD</code>. (<code class="code">resource.EntryFunc</code>). 120 </li><li>When resolving menu symbols (<code class="code">resource.Resource.GetMenu</code>). 121 </li><li>When retrieving node templates (<code class="code">resource.Resource.GetTemplate</code>). 122 </li></ul> 123 </div> 124 </div> 125 <hr> 126 <div class="nav-panel"> 127 <p> 128 Next: <a href="language.html">Handling languages</a>, Previous: <a href="render.html">Rendering</a>, Up: <a href="index.html">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> 129 </div> 130 131 132 133 </body> 134 </html>