< [Back](chapter-2.md) | [Summary](table-of-contents.md) | [Next](chapter-4.md) > # 🧠 **Memory: Stack, Heap, and Allocation** ## 1. Overview PROMETEU treats **memory as an explicit resource**. Nothing is allocated "for convenience". Nothing grows "automatically". Nothing is invisible. This chapter defines: - the **memory spaces** of the PROMETEU VM - how **Stack** and **Heap** work - the cost and consequences of **dynamic allocation** - how memory relates to **CAP and certification** --- ## 2. PROMETEU VM Memory Spaces The PROMETEU VM memory is divided into regions with clear responsibilities: ``` +---------------------------+ |Constant Pool | +---------------------------+ |Global Space | +---------------------------+ |Call Stack | | (Frames + Locals) | +---------------------------+ | Operand Stack | +---------------------------+ | Heap | +---------------------------+ ``` Each region: - has its own semantics - has defined limits - has a direct impact on execution cost --- ## 3. Operand Stack ### 3.1 Definition The **Operand Stack** is used for: - passing operands between instructions - intermediate results - expression evaluation It is: - **LIFO** - automatically growing within the frame - **reset** between frames (except explicitly persisted values) --- ### 3.2 Characteristics - does not store complex structures - stores primitive values or references - overflow or underflow are **fatal errors** > The operand stack is cheap, fast, and temporary. > --- ## 4. Call Stack ### 4.1 Execution Frames Each function call creates a **Call Frame**, containing: - local variables - parameters - return address - execution context Frames are created with: ``` PUSH_FRAME n ``` And destroyed with: ``` POP_FRAME ``` --- ### 4.2 Costs and Limits - frame creation has an explicit cost - maximum stack depth is limited - deep recursion is discouraged PROMETEU favors: - iteration - explicit state - conscious depth control --- ## 5. Global Space ### 5.1 Definition The **Global Space** stores: - global variables - persistent game state - long-term references Globals: - survive between frames - occupy memory permanently - count towards total memory usage --- ### 5.2 Conscious usage PROMETEU encourages: - few globals - compact structures - explicit initialization Globals are equivalent to **static RAM** in microcontrollers. --- ## 6. Heap ### 6.1 Definition The **Heap** is the dynamic memory region of the PROMETEU VM. It is used for: - objects - arrays - tables - composite structures Every allocation on the heap is done explicitly with: ``` ALLOC size ``` --- ### 6.2 Allocation Costs Allocating memory: - consumes **cycles** - consumes **available heap** - increases pressure on the system PROMETEU treats allocation as an **expensive operation by definition**. > Allocation is an architectural decision, not a detail. > --- ## 7. Heap Limits ### 7.1 Finite Heap The heap: - has a defined maximum size - can vary according to the active CAP - never grows dynamically Example: ``` Heap Limit:32KB Heap Used:28KB ``` Exceeding the limit: - does not crash the game - generates an execution error - appears in the certification report --- ### 7.2 Heap and CAP During a JAM or evaluation: - heap peak is measured - the value is compared to the CAP limit - non-compliances are recorded The game **continues running**, but the evidence is recorded. --- ## 8. Garbage Collection (GC) ### 8.1 Existence of GC PROMETEU may use **simple Garbage Collection**, with the following properties: - non-incremental (v0.1) - explicit cost - observable pauses - documented behavior GC **is not invisible**. --- ### 8.2 GC Cost When GC occurs: - cycles are consumed - the frame may be impacted - the event is recorded PROMETEU teaches: > "Creating garbage has a cost." > --- ## 9. Memory Best Practices PROMETEU explicitly encourages: - structure reuse - allocation outside the main loop - persistent buffers - pooling manual And discourages: - per-frame allocation - disposable temporary structures - unplanned growth --- ## 10. Relationship with Microcontrollers The PROMETEU memory model is intentionally similar to real MCUs: | MCU | PROMETEU | | --- | --- | | Static RAM | Global Space | | Stack | Call Stack | | Heap | Heap | | Allocation failure | Explicit error | | Fragmentation | Dev's responsibility | This creates a direct transfer of learning. --- ## 11. Pedagogical Implications This model allows teaching: - the difference between stack and heap - allocation cost - data lifetime - architectural impact of simple decisions - the relationship between memory and time Everything with **immediate and visible feedback**. --- ## 12. Summary - PROMETEU has well-defined memory spaces - stack is temporary and cheap - heap is finite and expensive - allocation has an explicit cost - GC is visible and measurable - memory participates in certification < [Back](chapter-2.md) | [Summary](table-of-contents.md) | [Next](chapter-4.md) >