cache.html (7346B)
1 <!DOCTYPE html> 2 <html> 3 <!-- Created by GNU Texinfo 7.1, 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>cache (vise)</title> 8 9 <meta name="description" content="cache (vise)"> 10 <meta name="keywords" content="cache (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="render.html" rel="next" title="render"> 20 <link href="navigation.html" rel="prev" title="navigation"> 21 <style type="text/css"> 22 <!-- 23 a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em} 24 span:hover a.copiable-link {visibility: visible} 25 ul.mark-bullet {list-style-type: disc} 26 --> 27 </style> 28 29 30 </head> 31 32 <body lang="en"> 33 <div class="chapter-level-extent" id="cache"> 34 <div class="nav-panel"> 35 <p> 36 Next: <a href="render.html" accesskey="n" rel="next">Rendering</a>, Previous: <a href="navigation.html" accesskey="p" rel="prev">Navigation</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> 37 </div> 38 <hr> 39 <h2 class="chapter" id="External-data"><span>7 External data<a class="copiable-link" href="#External-data"> ¶</a></span></h2> 40 41 <p>The <code class="code">LOAD</code> instruction enables the client implementer to define external data retrieval and processing code. 42 </p> 43 <p>It can be used to: 44 </p> 45 <ul class="itemize mark-bullet"> 46 <li>Query and store data 47 </li><li>Alter the menu execution flow 48 </li><li>Change language 49 </li></ul> 50 51 52 <a class="anchor" id="load_005fhandler"></a><ul class="mini-toc"> 53 <li><a href="#The-LOAD-handler" accesskey="1">The <code class="code">LOAD</code> handler</a></li> 54 <li><a href="#Size-limits" accesskey="2">Size limits</a></li> 55 <li><a href="#Scope" accesskey="3">Scope</a></li> 56 <li><a href="#Refreshing-cache-contents" accesskey="4">Refreshing cache contents</a></li> 57 </ul> 58 <div class="section-level-extent" id="The-LOAD-handler"> 59 <h3 class="section"><span>7.1 The <code class="code">LOAD</code> handler<a class="copiable-link" href="#The-LOAD-handler"> ¶</a></span></h3> 60 61 <p>In the <em class="emph">golang</em> code, the handler of the <code class="code">LOAD</code> instruction is an implementation of the <code class="code">resource.Resource</code> interface. 62 </p> 63 <p>It uses the method <code class="code">resource.Resource.FuncFor</code> to return a function pointer of type <code class="code">resource.EntryFunc</code> that can resolve the symbol. 64 </p> 65 <p>The <code class="code">resource.Result</code> value that it returns has the following capabilities: 66 </p> 67 <ul class="itemize mark-bullet"> 68 <li>Returned data payload (can be empty). 69 </li><li>A client-defined status code. 70 </li><li>A list of client-defined signal flags to <em class="emph">set</em>. 71 </li><li>A list of client-defined signal flags to <em class="emph">unset</em>. 72 </li></ul> 73 74 75 </div> 76 <div class="section-level-extent" id="Size-limits"> 77 <h3 class="section"><span>7.2 Size limits<a class="copiable-link" href="#Size-limits"> ¶</a></span></h3> 78 79 <p><code class="code">LOAD</code> instructions include a size parameter. 80 </p> 81 <p>This indicates the maximum byte size of the result that will be allowed. 82 </p> 83 <p>If the returned data payload exceeds this size, execution will terminate. 84 </p> 85 86 <ul class="mini-toc"> 87 <li><a href="#g_t_0022Sink_0022-symbols" accesskey="1">"Sink" symbols</a></li> 88 </ul> 89 <div class="subsection-level-extent" id="g_t_0022Sink_0022-symbols"> 90 <h4 class="subsection"><span>7.2.1 "Sink" symbols<a class="copiable-link" href="#g_t_0022Sink_0022-symbols"> ¶</a></span></h4> 91 92 <p>A sink is a symbol loaded with <code class="code">size</code> parameter <code class="code">0</code>. 93 </p> 94 <p>This allows the contents to expand to all remaining available space when rendering a template. See <a class="ref" href="render.html#dynamic_005ftemplates">Dynamic templates</a> for details. 95 </p> 96 97 </div> 98 </div> 99 <div class="section-level-extent" id="Scope"> 100 <h3 class="section"><span>7.3 Scope<a class="copiable-link" href="#Scope"> ¶</a></span></h3> 101 102 <p>The result data payload is stored under the symbol key for which it was loaded. It is kept in the cache until execution ascends from the execution stack level in which it was loaded. 103 </p> 104 <p>Consider the symbol <code class="code">foo</code> loaded at node <samp class="file">root/one/two</samp>. The symbol will still remain available in cache for e.g. node <samp class="file">root/one/two/three</samp>, but will be freed when entering <samp class="file">root/one</samp>. 105 </p> 106 107 <ul class="mini-toc"> 108 <li><a href="#Duplicate-LOAD" accesskey="1">Duplicate <code class="code">LOAD</code></a></li> 109 </ul> 110 <div class="subsection-level-extent" id="Duplicate-LOAD"> 111 <h4 class="subsection"><span>7.3.1 Duplicate <code class="code">LOAD</code><a class="copiable-link" href="#Duplicate-LOAD"> ¶</a></span></h4> 112 113 <p>If a <code class="code">LOAD</code> statement with the same symbol is issued twice within the same <em class="emph">scope</em>, it will fail and execution will terminate. 114 </p> 115 <p>If a <code class="code">LOAD</code> statement with the same symbol is issued twice in the same <em class="emph">node</em>, the latter will be ignored. 116 </p> 117 <p>For example, if <code class="code">LOAD</code> is called on node <samp class="file">foo/bar</samp>, then execution descends to <samp class="file">foo/bar/baz</samp> before returning to <samp class="file">foo/bar</samp>, the second time the <code class="code">LOAD</code> statement is encountered in <samp class="file">foo/bar</samp> will have no effect. 118 </p> 119 <p>However, if <code class="code">LOAD</code> is called on node <samp class="file">foo/bar/baz</samp>, then execution ascends to <samp class="file">foo/bar</samp> before returning to <samp class="file">foo/bar/baz</samp>, the <code class="code">LOAD</code> will be executed again. 120 </p> 121 122 </div> 123 </div> 124 <div class="section-level-extent" id="Refreshing-cache-contents"> 125 <h3 class="section"><span>7.4 Refreshing cache contents<a class="copiable-link" href="#Refreshing-cache-contents"> ¶</a></span></h3> 126 127 <p>The <code class="code">RELOAD</code> instruction will trigger the <code class="code">LOAD</code> handler again. The <code class="code">RELOAD</code> instruction is bound to the same size constraint as the initial <code class="code">LOAD</code>. 128 </p> 129 <p>It is not possible for the handler code to distinguish between a <code class="code">LOAD</code> and a <code class="code">RELOAD</code> instruction. 130 </p> 131 <p>Note that using <code class="code">RELOAD</code> when rendering multi-page menus can have unpredictable consequences for the lateral navigation state. 132 </p></div> 133 </div> 134 <hr> 135 <div class="nav-panel"> 136 <p> 137 Next: <a href="render.html">Rendering</a>, Previous: <a href="navigation.html">Navigation</a>, Up: <a href="index.html">Introduction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> 138 </div> 139 140 141 142 </body> 143 </html>