cache.texi (2972B)
1 @node cache 2 @chapter External data 3 4 The @code{LOAD} instruction enables the client implementer to define external data retrieval and processing code. 5 6 It can be used to: 7 8 @itemize 9 @item Query and store data 10 @item Alter the menu execution flow 11 @item Change language 12 @end itemize 13 14 15 @anchor{load_handler} 16 @section The @code{LOAD} handler 17 18 In the @emph{golang} code, the handler of the @code{LOAD} instruction is an implementation of the @code{resource.Resource} interface. 19 20 It uses the method @code{resource.Resource.FuncFor} to return a function pointer of type @code{resource.EntryFunc} that can resolve the symbol. 21 22 The @code{resource.Result} value that it returns has the following capabilities: 23 24 @itemize 25 @item Returned data payload (can be empty). 26 @item A client-defined status code. 27 @item A list of client-defined signal flags to @emph{set}. 28 @item A list of client-defined signal flags to @emph{unset}. 29 @end itemize 30 31 32 @section Size limits 33 34 @code{LOAD} instructions include a size parameter. 35 36 This indicates the maximum byte size of the result that will be allowed. 37 38 If the returned data payload exceeds this size, execution will terminate. 39 40 41 @subsection "Sink" symbols 42 43 A sink is a symbol loaded with @code{size} parameter @code{0}. 44 45 This allows the contents to expand to all remaining available space when rendering a template. See @ref{dynamic_templates, Dynamic templates} for details. 46 47 48 @section Scope 49 50 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. 51 52 Consider the symbol @code{foo} loaded at node @file{root/one/two}. The symbol will still remain available in cache for e.g. node @file{root/one/two/three}, but will be freed when entering @file{root/one}. 53 54 55 @subsection Duplicate @code{LOAD} 56 57 If a @code{LOAD} statement with the same symbol is issued twice within the same @emph{scope}, it will fail and execution will terminate. 58 59 If a @code{LOAD} statement with the same symbol is issued twice in the same @emph{node}, the latter will be ignored. 60 61 For example, if @code{LOAD} is called on node @file{foo/bar}, then execution descends to @file{foo/bar/baz} before returning to @file{foo/bar}, the second time the @code{LOAD} statement is encountered in @file{foo/bar} will have no effect. 62 63 However, if @code{LOAD} is called on node @file{foo/bar/baz}, then execution ascends to @file{foo/bar} before returning to @file{foo/bar/baz}, the @code{LOAD} will be executed again. 64 65 66 @section Refreshing cache contents 67 68 The @code{RELOAD} instruction will trigger the @code{LOAD} handler again. The @code{RELOAD} instruction is bound to the same size constraint as the initial @code{LOAD}. 69 70 It is not possible for the handler code to distinguish between a @code{LOAD} and a @code{RELOAD} instruction. 71 72 Note that using @code{RELOAD} when rendering multi-page menus can have unpredictable consequences for the lateral navigation state.