From a47660edc7e44204b35470502eaa76aacb92d2dc Mon Sep 17 00:00:00 2001 From: hanez Date: Tue, 14 Apr 2026 21:30:05 +0200 Subject: [PATCH] Added some VM configuration documentation. No code changes. (0.40.5) --- web/documentation/documentation.md | 1 + web/documentation/vm.md | 64 ++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+) create mode 100644 web/documentation/vm.md diff --git a/web/documentation/documentation.md b/web/documentation/documentation.md index 9f54448..3c73cac 100644 --- a/web/documentation/documentation.md +++ b/web/documentation/documentation.md @@ -41,6 +41,7 @@ The examples directory contains demonstrations of most Fun features, from basic - [includes/](./includes/) - Using local vs. system includes, FUN_LIB_DIR, DEFAULT_LIB_DIR, and namespaced includes with `as`. - [opcodes/](./opcodes/) - VM opcodes overview grouped by domain with brief behavior/stack notes. - [internals/](./internals/) - Implementation details: bytecode format, VM architecture, stacks/frames, parser, and dispatch. +- [vm/](./vm/) - VM configuration constants: maximum stack depth, local/global variable limits, and output buffer size. - [rust/](./rust/) - Writing Rust-backed opcodes and wiring them into the C VM; build/setup notes. - [examples/](./examples/) - How to run the examples and the interactive showcase script, with environment tips. - [testing/](./testing/) - How to build and run tests/targets with CMake/CTest, and where to add new tests. diff --git a/web/documentation/vm.md b/web/documentation/vm.md new file mode 100644 index 0000000..3ee75ab --- /dev/null +++ b/web/documentation/vm.md @@ -0,0 +1,64 @@ +--- +layout: page +published: true +noToc: false +noComments: false +noDate: false +title: Fun - VM Configuration Constants +subtitle: Detailed explanation of VM limits and memory management constants. +description: Learn about MAX_FRAMES, MAX_FRAME_LOCALS, MAX_GLOBALS, STACK_SIZE, and OUTPUT_SIZE in the Fun VM. +permalink: /documentation/vm/ +lang: en +tags: +- coding +- vm +- configuration +--- + +# Virtual Machine (VM) Configuration Constants + +The Fun Virtual Machine (VM) uses several fixed-size limits to manage memory and execution. These constants are defined in `src/vm.h` and can be adjusted if necessary by re-compiling the project. + +This document explains what each of these constants does in plain English. + +--- + +### `MAX_FRAMES` (Default: 128) +This constant defines the **maximum depth of the call stack**. + +When a function is called, the VM creates a "frame" to keep track of that function's execution (where it's at in the code and its local variables). If a function calls another function, a new frame is added on top. + +- **What happens if you exceed it?** If you have too many nested function calls (for example, in a deep recursion that never ends), the VM will run out of space for new frames. +- **Analogy:** Imagine a stack of dinner plates. `MAX_FRAMES` is the maximum height the stack can reach before it becomes unstable or hits the ceiling. + +### `MAX_FRAME_LOCALS` (Default: 64) +This constant limits the **number of local variables** each individual function can have. + +Every time a function is called, it gets its own space for variables that only exist within that function. + +- **What happens if you exceed it?** A single function cannot define more than 64 local variables. If it tries to use more, the VM won't be able to store them in the frame. +- **Analogy:** Think of this as the number of pockets in a single person's jacket. You can only carry 64 items in your pockets at once. + +### `MAX_GLOBALS` (Default: 128) +This constant defines the **maximum number of global variables** available to the entire program. + +Global variables are accessible from anywhere in your code, unlike local variables which belong to a specific function. + +- **What happens if you exceed it?** Your program cannot have more than 128 global variables defined at the same time. +- **Analogy:** This is like a shared community bulletin board. There is only enough room on the board for 128 different notices. + +### `STACK_SIZE` (Default: 1024) +This constant sets the size of the **operand stack**. + +The VM uses this stack for almost everything it does: adding numbers, comparing values, and passing arguments to functions. Most operations take values from the top of the stack, perform a calculation, and push the result back onto the stack. + +- **What happens if you exceed it?** Complex calculations or passing a very large number of arguments might fill up this stack, leading to a "stack overflow." +- **Analogy:** Imagine a workbench where you put tools and materials you are currently working on. `STACK_SIZE` is the area of that workbench. If it's too small, you can't work on complex projects. + +### `OUTPUT_SIZE` (Default: 1024) +This constant determines the size of the **output buffer**. + +When your program uses commands like `PRINT` or `ECHO`, the results are stored in an internal list before they are displayed or processed further. + +- **What happens if you exceed it?** The VM can only keep track of the last 1024 printed items in its internal history. +- **Analogy:** Think of this as a printer's paper tray. It can hold 1024 sheets of printed output. Once it's full, you might need to clear it or it might stop recording new output.