commit 8cfb76be58c5a2f8bb2053115892147bd92c039d
parent ee0dcc1e0bcfb93856f7c2bf06b70f2b498b5917
Author: lash <dev@holbrook.no>
Date: Sat, 31 Aug 2024 20:10:40 +0100
Add data provider to docs
Diffstat:
3 files changed, 146 insertions(+), 27 deletions(-)
diff --git a/doc/build/dev.html b/doc/build/dev.html
@@ -44,10 +44,11 @@ Next: <a href="cookbook.html" accesskey="n" rel="next">Common patterns</a>, Prev
<li><a href="#Code-repository-structure" accesskey="1">Code repository structure</a></li>
<li><a href="#Interacting-with-vise" accesskey="2">Interacting with <code class="code">vise</code></a></li>
<li><a href="#Resolving-resources" accesskey="3">Resolving resources</a></li>
-<li><a href="#Logging" accesskey="4">Logging</a></li>
-<li><a href="#Tools" accesskey="5">Tools</a></li>
-<li><a href="#Assembly-examples" accesskey="6">Assembly examples</a></li>
-<li><a href="#Bytecode-example" accesskey="7">Bytecode example</a></li>
+<li><a href="#Data-provider" accesskey="4">Data provider</a></li>
+<li><a href="#Logging" accesskey="5">Logging</a></li>
+<li><a href="#Tools" accesskey="6">Tools</a></li>
+<li><a href="#Assembly-examples" accesskey="7">Assembly examples</a></li>
+<li><a href="#Bytecode-example" accesskey="8">Bytecode example</a></li>
</ul>
<div class="section-level-extent" id="Code-repository-structure">
<h3 class="section"><span>11.1 Code repository structure<a class="copiable-link" href="#Code-repository-structure"> ¶</a></span></h3>
@@ -158,7 +159,7 @@ Next: <a href="cookbook.html" accesskey="n" rel="next">Common patterns</a>, Prev
<p>Please refer to <code class="code">engine.Config</code> for details.
</p>
-</div>
+<a class="anchor" id="sessions"></a></div>
<div class="subsection-level-extent" id="Sessions">
<h4 class="subsection"><span>11.2.3 Sessions<a class="copiable-link" href="#Sessions"> ¶</a></span></h4>
@@ -275,8 +276,72 @@ Next: <a href="cookbook.html" accesskey="n" rel="next">Common patterns</a>, Prev
</div>
</div>
</div>
+<div class="section-level-extent" id="Data-provider">
+<h3 class="section"><span>11.4 Data provider<a class="copiable-link" href="#Data-provider"> ¶</a></span></h3>
+
+<p>The <code class="code">db.Db</code> interface provides methods to get and set data to key-value stores.
+</p>
+<p>The storage keys are partitioned according to the <a class="ref" href="#sessions">session</a> context, aswell as what type of data is being stored or retrieved.
+</p>
+<p>The interface and the data types are defined in <code class="code">db/db.go</code>.
+</p>
+<p>The included implementations are:
+</p>
+<dl class="table">
+<dt><code class="code">MemDb</code></dt>
+<dd><p>An volatile, in-process store. Used in most tests.
+</p></dd>
+<dt><code class="code">FsDb</code></dt>
+<dd><p>A filesystem-backed store using subdirectories to separate sessions.
+</p></dd>
+<dt><code class="code">GdbmDb</code></dt>
+<dd><p>A <a class="url" href="https://www.gnu.org/software/gdbm/gdbm">gdbm</a> backed store.
+</p></dd>
+<dt><code class="code">PgDb</code></dt>
+<dd><p>A <a class="url" href="https://www.postgresql.org/">Postgres</a> backed store, using a single table with two <code class="code">BYTEA</code> columns and a connection pool.
+</p></dd>
+</dl>
+
+
+<ul class="mini-toc">
+<li><a href="#Uses" accesskey="1">Uses</a></li>
+<li><a href="#Using-data-provider-with-resources" accesskey="2">Using data provider with resources</a></li>
+<li><a href="#State-persistence" accesskey="3">State persistence</a></li>
+</ul>
+<div class="subsection-level-extent" id="Uses">
+<h4 class="subsection"><span>11.4.1 Uses<a class="copiable-link" href="#Uses"> ¶</a></span></h4>
+
+<p><code class="code">db.Db</code> may fulfill all local data requirements in <code class="code">vise</code>, including:
+</p>
+<ul class="itemize mark-bullet">
+<li>Resource retrieval
+</li><li>State and cache persistence
+</li><li>Application data
+</li></ul>
+
+
+</div>
+<div class="subsection-level-extent" id="Using-data-provider-with-resources">
+<h4 class="subsection"><span>11.4.2 Using data provider with resources<a class="copiable-link" href="#Using-data-provider-with-resources"> ¶</a></span></h4>
+
+<p>The <code class="code">resource.dbGetter</code> assists in using a <code class="code">db.Db</code> implementation.
+</p>
+<p>Its functions may be assigned individually to a <code class="code">resource.MenuResource</code>, allowing for co-existence of <code class="code">db.Db</code> backed resources, aswell as from other sources.
+</p>
+
+</div>
+<div class="subsection-level-extent" id="State-persistence">
+<h4 class="subsection"><span>11.4.3 State persistence<a class="copiable-link" href="#State-persistence"> ¶</a></span></h4>
+
+<p>Any asynchronous or consecutive synchronous operation of the <code class="code">engine.Engine</code> requires persistence of the associated <code class="code">state.State</code> and <code class="code">cache.Memory</code>. This is achieved using <code class="code">persist.Persister</code>, instantiated with a <code class="code">db.Db</code> implementation.
+</p>
+<p>The <code class="code">db.Db</code> used for persistence does not need to be the same as e.g. used for retrieval of resources, or even for application data.
+</p>
+
+</div>
+</div>
<div class="section-level-extent" id="Logging">
-<h3 class="section"><span>11.4 Logging<a class="copiable-link" href="#Logging"> ¶</a></span></h3>
+<h3 class="section"><span>11.5 Logging<a class="copiable-link" href="#Logging"> ¶</a></span></h3>
<p>Loglevels are set at compile-time using the following build tags:
</p>
@@ -298,7 +363,7 @@ Next: <a href="cookbook.html" accesskey="n" rel="next">Common patterns</a>, Prev
</div>
<div class="section-level-extent" id="Tools">
-<h3 class="section"><span>11.5 Tools<a class="copiable-link" href="#Tools"> ¶</a></span></h3>
+<h3 class="section"><span>11.6 Tools<a class="copiable-link" href="#Tools"> ¶</a></span></h3>
<p>Located in the <samp class="file">dev/</samp> directory of the source code repository.
</p>
@@ -311,7 +376,7 @@ Next: <a href="cookbook.html" accesskey="n" rel="next">Common patterns</a>, Prev
<li><a href="#Interactive-case-examples" accesskey="5">Interactive case examples</a></li>
</ul>
<div class="subsection-level-extent" id="Test-data-generation">
-<h4 class="subsection"><span>11.5.1 Test data generation<a class="copiable-link" href="#Test-data-generation"> ¶</a></span></h4>
+<h4 class="subsection"><span>11.6.1 Test data generation<a class="copiable-link" href="#Test-data-generation"> ¶</a></span></h4>
<div class="example">
<pre class="example-preformatted">go run ./dev/gendata/ <directory>
@@ -322,7 +387,7 @@ Next: <a href="cookbook.html" accesskey="n" rel="next">Common patterns</a>, Prev
</div>
<div class="subsection-level-extent" id="Interactive-runner">
-<h4 class="subsection"><span>11.5.2 Interactive runner<a class="copiable-link" href="#Interactive-runner"> ¶</a></span></h4>
+<h4 class="subsection"><span>11.6.2 Interactive runner<a class="copiable-link" href="#Interactive-runner"> ¶</a></span></h4>
<div class="example">
<pre class="example-preformatted">go run ./dev/interactive [-d <data_directory>] [--root <root_symbol>] [--session-id <session_id>] [--persist]
@@ -343,7 +408,7 @@ Next: <a href="cookbook.html" accesskey="n" rel="next">Common patterns</a>, Prev
</div>
<div class="subsection-level-extent" id="Assembler">
-<h4 class="subsection"><span>11.5.3 Assembler<a class="copiable-link" href="#Assembler"> ¶</a></span></h4>
+<h4 class="subsection"><span>11.6.3 Assembler<a class="copiable-link" href="#Assembler"> ¶</a></span></h4>
<div class="example">
<pre class="example-preformatted">go run ./dev/asm <assembly_file>
@@ -354,7 +419,7 @@ Next: <a href="cookbook.html" accesskey="n" rel="next">Common patterns</a>, Prev
</div>
<div class="subsection-level-extent" id="Disassembler">
-<h4 class="subsection"><span>11.5.4 Disassembler<a class="copiable-link" href="#Disassembler"> ¶</a></span></h4>
+<h4 class="subsection"><span>11.6.4 Disassembler<a class="copiable-link" href="#Disassembler"> ¶</a></span></h4>
<div class="example">
<pre class="example-preformatted">go run ./dev/disasm/ <binary_file>
@@ -365,7 +430,7 @@ Next: <a href="cookbook.html" accesskey="n" rel="next">Common patterns</a>, Prev
</div>
<div class="subsection-level-extent" id="Interactive-case-examples">
-<h4 class="subsection"><span>11.5.5 Interactive case examples<a class="copiable-link" href="#Interactive-case-examples"> ¶</a></span></h4>
+<h4 class="subsection"><span>11.6.5 Interactive case examples<a class="copiable-link" href="#Interactive-case-examples"> ¶</a></span></h4>
<p>Found in <samp class="file">examples/</samp>.
</p>
@@ -406,14 +471,14 @@ Next: <a href="cookbook.html" accesskey="n" rel="next">Common patterns</a>, Prev
</div>
</div>
<div class="section-level-extent" id="Assembly-examples">
-<h3 class="section"><span>11.6 Assembly examples<a class="copiable-link" href="#Assembly-examples"> ¶</a></span></h3>
+<h3 class="section"><span>11.7 Assembly examples<a class="copiable-link" href="#Assembly-examples"> ¶</a></span></h3>
<p>See <samp class="file">testdata/*.vis</samp>
</p>
</div>
<div class="section-level-extent" id="Bytecode-example">
-<h3 class="section"><span>11.7 Bytecode example<a class="copiable-link" href="#Bytecode-example"> ¶</a></span></h3>
+<h3 class="section"><span>11.8 Bytecode example<a class="copiable-link" href="#Bytecode-example"> ¶</a></span></h3>
<p>Currently the following rules apply for encoding in version <code class="code">0</code>:
</p>
@@ -429,13 +494,13 @@ Next: <a href="cookbook.html" accesskey="n" rel="next">Common patterns</a>, Prev
<li><a href="#Example" accesskey="1">Example</a></li>
</ul>
<div class="subsection-level-extent" id="Example">
-<h4 class="subsection"><span>11.7.1 Example<a class="copiable-link" href="#Example"> ¶</a></span></h4>
+<h4 class="subsection"><span>11.8.1 Example<a class="copiable-link" href="#Example"> ¶</a></span></h4>
<p>(Minimal, WIP)
</p>
<pre class="verbatim">000a 03666f6f 05746f666f6f # MOUT tofoo foo - display a menu entry for choice "foo", described by "to foo"
0008 03666f6f 03626172 # INCMP bar foo - move to node "bar" if input is "FOO"
-0001 0461696565 01 01 # CATCH aiee 1 1 - move to node "aiee" (and immediately halt) if input match flag (1) is not set (1)
+0001 0461696565 01 01 # CATCH aiee 1 1 - move to node "aiee" (and immediately halt) if input match flag (1) is set (1)
0003 04616263 020104 # LOAD abc 260 - execute code symbol "abc" with a result size limit of 260 (2 byte BE integer, 0x0104)
0003 04646566 00 # LOAD def 0 - execute code symbol "abc" with no size limit (sink)
0005 04616263 # MAP abc - make "abc" available for renderer
diff --git a/doc/build/index.html b/doc/build/index.html
@@ -211,19 +211,25 @@ Next: <a href="overview.html" accesskey="n" rel="next">Overview</a> [<a h
<li><a id="toc-External-symbols-_0028resource_002eResource_002eFuncFor_0029" href="dev.html#External-symbols-_0028resource_002eResource_002eFuncFor_0029">11.3.2.4 External symbols (<code class="code">resource.Resource.FuncFor</code>)</a></li>
</ul></li>
</ul></li>
- <li><a id="toc-Logging" href="dev.html#Logging">11.4 Logging</a></li>
- <li><a id="toc-Tools" href="dev.html#Tools">11.5 Tools</a>
+ <li><a id="toc-Data-provider" href="dev.html#Data-provider">11.4 Data provider</a>
<ul class="toc-numbered-mark">
- <li><a id="toc-Test-data-generation" href="dev.html#Test-data-generation">11.5.1 Test data generation</a></li>
- <li><a id="toc-Interactive-runner" href="dev.html#Interactive-runner">11.5.2 Interactive runner</a></li>
- <li><a id="toc-Assembler" href="dev.html#Assembler">11.5.3 Assembler</a></li>
- <li><a id="toc-Disassembler" href="dev.html#Disassembler">11.5.4 Disassembler</a></li>
- <li><a id="toc-Interactive-case-examples" href="dev.html#Interactive-case-examples">11.5.5 Interactive case examples</a></li>
+ <li><a id="toc-Uses" href="dev.html#Uses">11.4.1 Uses</a></li>
+ <li><a id="toc-Using-data-provider-with-resources" href="dev.html#Using-data-provider-with-resources">11.4.2 Using data provider with resources</a></li>
+ <li><a id="toc-State-persistence" href="dev.html#State-persistence">11.4.3 State persistence</a></li>
</ul></li>
- <li><a id="toc-Assembly-examples" href="dev.html#Assembly-examples">11.6 Assembly examples</a></li>
- <li><a id="toc-Bytecode-example" href="dev.html#Bytecode-example">11.7 Bytecode example</a>
+ <li><a id="toc-Logging" href="dev.html#Logging">11.5 Logging</a></li>
+ <li><a id="toc-Tools" href="dev.html#Tools">11.6 Tools</a>
<ul class="toc-numbered-mark">
- <li><a id="toc-Example" href="dev.html#Example">11.7.1 Example</a></li>
+ <li><a id="toc-Test-data-generation" href="dev.html#Test-data-generation">11.6.1 Test data generation</a></li>
+ <li><a id="toc-Interactive-runner" href="dev.html#Interactive-runner">11.6.2 Interactive runner</a></li>
+ <li><a id="toc-Assembler" href="dev.html#Assembler">11.6.3 Assembler</a></li>
+ <li><a id="toc-Disassembler" href="dev.html#Disassembler">11.6.4 Disassembler</a></li>
+ <li><a id="toc-Interactive-case-examples" href="dev.html#Interactive-case-examples">11.6.5 Interactive case examples</a></li>
+ </ul></li>
+ <li><a id="toc-Assembly-examples" href="dev.html#Assembly-examples">11.7 Assembly examples</a></li>
+ <li><a id="toc-Bytecode-example" href="dev.html#Bytecode-example">11.8 Bytecode example</a>
+ <ul class="toc-numbered-mark">
+ <li><a id="toc-Example" href="dev.html#Example">11.8.1 Example</a></li>
</ul></li>
</ul></li>
<li><a id="toc-Common-patterns" href="cookbook.html">12 Common patterns</a>
diff --git a/doc/texinfo/dev.texi b/doc/texinfo/dev.texi
@@ -76,6 +76,7 @@ The engine configuration defines the top-level parameters for the execution envi
Please refer to @code{engine.Config} for details.
+@anchor{sessions}
@subsection Sessions
The @code{engine.Config.SessionId} is used to disambiguate the end-user that is interacting with the engine.
@@ -162,6 +163,53 @@ A missing entry will result in load failure and program termination.
The implementation contains no built-in handling of the @code{SessionId} supplied by the context.
+@section Data provider
+
+The @code{db.Db} interface provides methods to get and set data to key-value stores.
+
+The storage keys are partitioned according to the @ref{sessions, session} context, aswell as what type of data is being stored or retrieved.
+
+The interface and the data types are defined in @code{db/db.go}.
+
+The included implementations are:
+
+@table @code
+@item MemDb
+An volatile, in-process store. Used in most tests.
+@item FsDb
+A filesystem-backed store using subdirectories to separate sessions.
+@item GdbmDb
+A @url{https://www.gnu.org/software/gdbm/gdbm,gdbm} backed store.
+@item PgDb
+A @url{https://www.postgresql.org/,Postgres} backed store, using a single table with two @code{BYTEA} columns and a connection pool.
+@end table
+
+
+@subsection Uses
+
+@code{db.Db} may fulfill all local data requirements in @code{vise}, including:
+
+@itemize
+@item Resource retrieval
+@item State and cache persistence
+@item Application data
+@end itemize
+
+
+@subsection Using data provider with resources
+
+The @code{resource.dbGetter} assists in using a @code{db.Db} implementation.
+
+Its functions may be assigned individually to a @code{resource.MenuResource}, allowing for co-existence of @code{db.Db} backed resources, aswell as from other sources.
+
+
+@subsection State persistence
+
+Any asynchronous or consecutive synchronous operation of the @code{engine.Engine} requires persistence of the associated @code{state.State} and @code{cache.Memory}. This is achieved using @code{persist.Persister}, instantiated with a @code{db.Db} implementation.
+
+The @code{db.Db} used for persistence does not need to be the same as e.g. used for retrieval of resources, or even for application data.
+
+
@section Logging
Loglevels are set at compile-time using the following build tags:
@@ -291,7 +339,7 @@ Currently the following rules apply for encoding in version @code{0}:
@verbatim
000a 03666f6f 05746f666f6f # MOUT tofoo foo - display a menu entry for choice "foo", described by "to foo"
0008 03666f6f 03626172 # INCMP bar foo - move to node "bar" if input is "FOO"
-0001 0461696565 01 01 # CATCH aiee 1 1 - move to node "aiee" (and immediately halt) if input match flag (1) is not set (1)
+0001 0461696565 01 01 # CATCH aiee 1 1 - move to node "aiee" (and immediately halt) if input match flag (1) is set (1)
0003 04616263 020104 # LOAD abc 260 - execute code symbol "abc" with a result size limit of 260 (2 byte BE integer, 0x0104)
0003 04646566 00 # LOAD def 0 - execute code symbol "abc" with no size limit (sink)
0005 04616263 # MAP abc - make "abc" available for renderer
