From d6088005ef565b4c42de2f822186bdcfe22e9ed8 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 13 Oct 2022 21:11:41 -0700
Subject: [PATCH] docs(tvix/eval) vm: explain VM::{frames,stack,with_stack}

Signed-off-by: Adam Joseph <adam@westernsemico.com>
Change-Id: I94ba31ae25c1ff744f929a722c76a0c33cc361ff
Reviewed-on: https://cl.tvl.fyi/c/depot/+/7016
Reviewed-by: tazjin <tazjin@tvl.su>
Tested-by: BuildkiteCI
---
 tvix/eval/src/vm.rs | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/tvix/eval/src/vm.rs b/tvix/eval/src/vm.rs
index e1f9d3096..52de99f49 100644
--- a/tvix/eval/src/vm.rs
+++ b/tvix/eval/src/vm.rs
@@ -38,11 +38,21 @@ impl CallFrame {
 }
 
 pub struct VM<'o> {
+    /// The VM call stack.  One element is pushed onto this stack
+    /// each time a function is called or a thunk is forced.
     frames: Vec<CallFrame>,
+
+    /// The VM value stack.  This is actually a "stack of stacks",
+    /// with one stack-of-Values for each CallFrame in frames.  This
+    /// is represented as a Vec<Value> rather than as
+    /// Vec<Vec<Value>> or a Vec<Value> inside CallFrame for
+    /// efficiency reasons: it avoids having to allocate a Vec on
+    /// the heap each time a CallFrame is entered.
     stack: Vec<Value>,
 
-    /// Stack indices of attribute sets from which variables should be
-    /// dynamically resolved (`with`).
+    /// Stack indices (absolute indexes into `stack`) of attribute
+    /// sets from which variables should be dynamically resolved
+    /// (`with`).
     with_stack: Vec<usize>,
 
     /// Runtime warnings collected during evaluation.