add MEMORY to CHAIN

Author: braindigitalis

docpages/basic-language-reference/keywords/CHAIN.md

@@ -1,23 +1,43 @@
 \page CHAIN CHAIN Keyword
+
 ```basic
-CHAIN string-expression[,boolean-expression]
+CHAIN string-expression[,boolean-expression] [MEMORY SMALL|MEDIUM|LARGE|HUGE]
 ```
 
-Starts a new BASIC program, pausing the current program until the new one finishes.  
+Starts a new BASIC program, pausing the current program until the new one finishes.
 The string expression must evaluate to the **filename** of a program accessible from the filesystem.
 
-- Any variables marked as \ref GLOBAL "GLOBAL" will be shared with the child program.
-- When the chained program terminates, control returns to the line immediately following the `CHAIN` statement in the calling program.  
-- Variables not marked as global are not visible to the chained program.
-- If the optional boolean expression is included and evaluates to true, the program will be launched as a task in the background and the caller will resume immediately.
+* Any variables marked as \ref GLOBAL "GLOBAL" will be shared with the child program.
+* When the chained program terminates, control returns to the line immediately following the `CHAIN` statement in the calling program.
+* Variables not marked as global are not visible to the chained program.
+* If the optional boolean expression is included and evaluates to true, the program will be launched as a task in the background and the caller will resume immediately.
+* The optional `MEMORY` clause selects the memory model used by the new program.
+
+---
+
+##### Memory Models
+
+The `MEMORY` option controls the size of the allocator used by the child program:
+
+* `SMALL`   — up to 32 MiB per allocation
+* `MEDIUM`  — up to 64 MiB per allocation *(default)*
+* `LARGE`   — up to 128 MiB per allocation
+* `HUGE`    — up to 256 MiB per allocation
 
+If not specified, the child program uses the **same memory model as the caller**, or `MEDIUM` if no parent model applies.
+
+If the requested memory model cannot be allocated, the `CHAIN` will fail with an out-of-memory error.
+
+\remark The memory model does not limit the total memory a program may use.It limits the size of any single contiguous allocation (for example, a string or buffer), and programs may use more memory overall but individual allocations cannot exceed the selected model.
+
+---
 
 \remark `CHAIN` resolves relative paths from the **current working directory**.
 \remark Use absolute paths (e.g. `/programs/login`) if you don’t want this to depend on `CHDIR`.
 
 ---
 
-##### Example
+##### Examples
 
 ```basic
 PRINT "Before chain"
@@ -26,16 +46,30 @@ CHAIN "childprog"
 PRINT "Back again, X = "; X
 ```
 
-If `childprog` uses the global variable `X`, it will see the value `42`.  
-After `childprog` ends, execution resumes.
+```basic
+CHAIN "worker", TRUE MEMORY SMALL
+```
+
+```basic
+CHAIN "bigdata" MEMORY LARGE
+```
+
+```basic
+CHAIN "analysis" MEMORY HUGE
+```
 
 ---
 
 ##### Notes
-- Chained programs run in a **new interpreter instance** within a new process. The parent remains suspended until the child exits, unless the child is launched as a background task.
-- A chained program may itself issue `CHAIN` statements, nesting as required.  
-- If the file specified in `string-expression` cannot be found, an error is raised (and can be caught with `ON ERROR`).
-- Unlike BBC BASIC, Retro Rocket’s `CHAIN` does **not** discard the caller - the parent program continues afterwards.
+
+* Chained programs run in a **new interpreter instance** within a new process. The parent remains suspended until the child exits, unless the child is launched as a background task.
+* A chained program may itself issue `CHAIN` statements, nesting as required.
+* If the file specified in `string-expression` cannot be found, an error is raised (and can be caught with `ON ERROR`).
+* The memory model determines the **maximum size of any single allocation**, not the total memory usage of the program.
+* Unlike BBC BASIC, Retro Rocket’s `CHAIN` does **not** discard the caller - the parent program continues afterwards.
+
+---
 
 **See also:**
 \ref GLOBAL "GLOBAL", \ref LIBRARY "LIBRARY"
+

docs/BUFFERTOSTRINGS.html

@@ -164,9 +164,9 @@ <h2 class="doxsection"><a class="anchor" id="encoding-format-1"></a>
 <h2 class="doxsection"><a class="anchor" id="errors-5"></a>
 Errors</h2>
 <ul>
-<li>Invalid memory address → error</li>
-<li>Negative <span class="tt">length</span> → error</li>
-<li>Encoded result exceeds <span class="tt">MAX_STRINGLEN</span> → error</li>
+<li>Invalid memory address</li>
+<li>Negative <span class="tt">length</span></li>
+<li>Encoded result is too large to allocate a string variable</li>
 </ul>
 <hr  />
 <h2 class="doxsection"><a class="anchor" id="example-3"></a>

docs/CHAIN.html

@@ -123,38 +123,53 @@
   <div class="headertitle"><div class="title">CHAIN Keyword </div></div>
 </div><!--header-->
 <div class="contents">
-<div class="textblock"><div class="fragment"><div class="line">CHAIN string-expression[,boolean-expression]</div>
-</div><!-- fragment --><p>Starts a new BASIC program, pausing the current program until the new one finishes. <br  />
- The string expression must evaluate to the <b>filename</b> of a program accessible from the filesystem.</p>
+<div class="textblock"><div class="fragment"><div class="line">CHAIN string-expression[,boolean-expression] [MEMORY SMALL|MEDIUM|LARGE|HUGE]</div>
+</div><!-- fragment --><p>Starts a new BASIC program, pausing the current program until the new one finishes. The string expression must evaluate to the <b>filename</b> of a program accessible from the filesystem.</p>
 <ul>
 <li>Any variables marked as <a class="el" href="GLOBAL.html">GLOBAL</a> will be shared with the child program.</li>
-<li>When the chained program terminates, control returns to the line immediately following the <span class="tt">CHAIN</span> statement in the calling program. <br  />
-</li>
+<li>When the chained program terminates, control returns to the line immediately following the <span class="tt">CHAIN</span> statement in the calling program.</li>
 <li>Variables not marked as global are not visible to the chained program.</li>
 <li>If the optional boolean expression is included and evaluates to true, the program will be launched as a task in the background and the caller will resume immediately.</li>
+<li>The optional <span class="tt">MEMORY</span> clause selects the memory model used by the new program.</li>
 </ul>
+<hr  />
+<h5 class="doxsection"><a class="anchor" id="memory-models"></a>
+Memory Models</h5>
+<p>The <span class="tt">MEMORY</span> option controls the size of the allocator used by the child program:</p>
+<ul>
+<li><span class="tt">SMALL</span> — up to 32 MiB per allocation</li>
+<li><span class="tt">MEDIUM</span> — up to 64 MiB per allocation <em>(default)</em></li>
+<li><span class="tt">LARGE</span> — up to 128 MiB per allocation</li>
+<li><span class="tt">HUGE</span> — up to 256 MiB per allocation</li>
+</ul>
+<p>If not specified, the child program uses the <b>same memory model as the caller</b>, or <span class="tt">MEDIUM</span> if no parent model applies.</p>
+<p>If the requested memory model cannot be allocated, the <span class="tt">CHAIN</span> will fail with an out-of-memory error.</p>
+<dl class="section remark"><dt>Remarks</dt><dd>The memory model does not limit the total memory a program may use.It limits the size of any single contiguous allocation (for example, a string or buffer), and programs may use more memory overall but individual allocations cannot exceed the selected model.</dd></dl>
+<hr  />
 <dl class="section remark"><dt>Remarks</dt><dd><span class="tt">CHAIN</span> resolves relative paths from the <b>current working directory</b>. </dd>
 <dd>
 Use absolute paths (e.g. <span class="tt">/programs/login</span>) if you don’t want this to depend on <span class="tt">CHDIR</span>.</dd></dl>
 <hr  />
-<h5 class="doxsection"><a class="anchor" id="example-7"></a>
-Example</h5>
+<h5 class="doxsection"><a class="anchor" id="examples-150"></a>
+Examples</h5>
 <div class="fragment"><div class="line">PRINT &quot;Before chain&quot;</div>
 <div class="line">GLOBAL X = 42</div>
 <div class="line">CHAIN &quot;childprog&quot;</div>
 <div class="line">PRINT &quot;Back again, X = &quot;; X</div>
-</div><!-- fragment --><p>If <span class="tt">childprog</span> uses the global variable <span class="tt">X</span>, it will see the value <span class="tt">42</span>. <br  />
- After <span class="tt">childprog</span> ends, execution resumes.</p>
-<hr  />
+</div><!-- fragment --><div class="fragment"><div class="line">CHAIN &quot;worker&quot;, TRUE MEMORY SMALL</div>
+</div><!-- fragment --><div class="fragment"><div class="line">CHAIN &quot;bigdata&quot; MEMORY LARGE</div>
+</div><!-- fragment --><div class="fragment"><div class="line">CHAIN &quot;analysis&quot; MEMORY HUGE</div>
+</div><!-- fragment --><hr  />
 <h5 class="doxsection"><a class="anchor" id="notes-148"></a>
 Notes</h5>
 <ul>
 <li>Chained programs run in a <b>new interpreter instance</b> within a new process. The parent remains suspended until the child exits, unless the child is launched as a background task.</li>
-<li>A chained program may itself issue <span class="tt">CHAIN</span> statements, nesting as required. <br  />
-</li>
+<li>A chained program may itself issue <span class="tt">CHAIN</span> statements, nesting as required.</li>
 <li>If the file specified in <span class="tt">string-expression</span> cannot be found, an error is raised (and can be caught with <span class="tt">ON ERROR</span>).</li>
+<li>The memory model determines the <b>maximum size of any single allocation</b>, not the total memory usage of the program.</li>
 <li>Unlike BBC BASIC, Retro Rocket’s <span class="tt">CHAIN</span> does <b>not</b> discard the caller - the parent program continues afterwards.</li>
 </ul>
+<hr  />
 <p><b>See also:</b> <a class="el" href="GLOBAL.html">GLOBAL</a>, <a class="el" href="LIBRARY.html">LIBRARY</a> </p>
 </div></div><!-- contents -->
 </div><!-- PageDoc -->

docs/CHDIR.html

@@ -138,7 +138,7 @@
 <dd>
 Directory traversal is only possible by specifying absolute or relative names explicitly.</dd></dl>
 <hr  />
-<h4 class="doxsection"><a class="anchor" id="example-8"></a>
+<h4 class="doxsection"><a class="anchor" id="example-7"></a>
 Example</h4>
 <div class="fragment"><div class="line">CHDIR &quot;/programs&quot;</div>
 <div class="line">CHAIN &quot;demo&quot;</div>

docs/CLOSE.html

@@ -135,7 +135,7 @@
 <dd>
 A numeric literal or expression is <b>not</b> accepted.</dd></dl>
 <hr  />
-<h5 class="doxsection"><a class="anchor" id="example-9"></a>
+<h5 class="doxsection"><a class="anchor" id="example-8"></a>
 Example</h5>
 <div class="fragment"><div class="line">FH = OPENOUT(&quot;log.txt&quot;)</div>
 <div class="line">WRITE FH, &quot;hello&quot;</div>

docs/CLS.html

@@ -130,7 +130,7 @@
 <li>Subsequent text and graphics draw onto a blank screen using the active colours.</li>
 </ul>
 <hr  />
-<h5 class="doxsection"><a class="anchor" id="example-10"></a>
+<h5 class="doxsection"><a class="anchor" id="example-9"></a>
 Example</h5>
 <div class="fragment"><div class="line">PRINT &quot;Hello!&quot;</div>
 <div class="line">CIRCLE 200, 150, 50, TRUE</div>

docs/COLOUR.html

@@ -131,7 +131,7 @@
 </div>
 <dl class="section note"><dt>Note</dt><dd>Both British and American spellings are accepted: <span class="tt">COLOUR</span> and <span class="tt">COLOR</span>.</dd></dl>
 <hr  />
-<h5 class="doxsection"><a class="anchor" id="example-11"></a>
+<h5 class="doxsection"><a class="anchor" id="example-10"></a>
 Example</h5>
 <div class="fragment"><div class="line">COLOUR 14</div>
 <div class="line">PRINT &quot;This text is bright yellow.&quot;</div>

docs/CURSOR.html

@@ -132,7 +132,7 @@
 </ul>
 <p>After moving the cursor, subsequent <a class="el" href="PRINT.html">PRINT</a> output starts at that position.</p>
 <hr  />
-<h5 class="doxsection"><a class="anchor" id="example-12"></a>
+<h5 class="doxsection"><a class="anchor" id="example-11"></a>
 Example</h5>
 <div class="fragment"><div class="line">CLS</div>
 <div class="line">CURSOR 10, 5</div>

docs/DATA.html

@@ -134,7 +134,7 @@
 <p>Values are stored at program load time and are not re-parsed during execution.</p>
 <p>Multiple <span class="tt">DATA</span> statements are concatenated into a single continuous data stream.</p>
 <hr  />
-<h5 class="doxsection"><a class="anchor" id="example-13"></a>
+<h5 class="doxsection"><a class="anchor" id="example-12"></a>
 Example</h5>
 <div class="fragment"><div class="line">DATA 10, 20</div>
 <div class="line">DATA 1.5</div>

docs/DATASET.html

@@ -127,7 +127,7 @@
 </div><!-- fragment --><p>Defines a named position within the <span class="tt">DATA</span> stream.</p>
 <p>The name is set to the current position in the <span class="tt">DATA</span> stream at that point in the program, so it can be used later with <span class="tt">RESTORE</span>.</p>
 <hr  />
-<h5 class="doxsection"><a class="anchor" id="example-14"></a>
+<h5 class="doxsection"><a class="anchor" id="example-13"></a>
 Example</h5>
 <div class="fragment"><div class="line">DATA 10, 20</div>
 <div class="line">DATASET numbers</div>