From 4b01e594d5d5cb806f6fe6eef1c30069748369cd Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 13 Oct 2022 13:41:30 -0700 Subject: docs(tvix/eval): upvalues.rs: define "upvalue", comment with_stack This commit adds a comment for the benefit of non-Lua-users explaining what an upvalue is. It also adds a comment explaining what `with_stack` does, including a brief reminder of nix's slightly-unusual-but-well-justified handling of this construct. Signed-off-by: Adam Joseph Change-Id: If6d0e133292451af906e1c728e34010f99be8c7c Reviewed-on: https://cl.tvl.fyi/c/depot/+/7007 Reviewed-by: j4m3s Reviewed-by: tazjin Tested-by: BuildkiteCI --- tvix/eval/src/upvalues.rs | 39 ++++++++++++++++++++++++++++++--------- 1 file changed, 30 insertions(+), 9 deletions(-) (limited to 'tvix/eval') diff --git a/tvix/eval/src/upvalues.rs b/tvix/eval/src/upvalues.rs index 7dd25b9f3f..6da9bcf7cc 100644 --- a/tvix/eval/src/upvalues.rs +++ b/tvix/eval/src/upvalues.rs @@ -2,6 +2,10 @@ //! relevant to both thunks (delayed computations for lazy-evaluation) //! as well as closures (lambdas that capture variables from the //! surrounding scope). +//! +//! The upvalues of a scope are whatever data are needed at runtime +//! in order to resolve each free variable in the scope to a value. +//! "Upvalue" is a term taken from Lua. use std::{ cell::{Ref, RefMut}, @@ -10,26 +14,43 @@ use std::{ use crate::{opcode::UpvalueIdx, Value}; -/// Structure for carrying upvalues inside of thunks & closures. The -/// implementation of this struct encapsulates the logic for capturing -/// and accessing upvalues. +/// Structure for carrying upvalues of an UpvalueCarrier. The +/// implementation of this struct encapsulates the logic for +/// capturing and accessing upvalues. +/// +/// Nix's `with` cannot be used to shadow an enclosing binding -- +/// like Rust's `use xyz::*` construct, but unlike Javascript's +/// `with (xyz)`. This means that Nix has two kinds of identifiers, +/// which can be distinguished at compile time: +/// +/// - Static identifiers, which are bound in some enclosing scope by +/// `let`, `name:` or `{name}:` +/// - Dynamic identifiers, which are not bound in any enclosing +/// scope #[derive(Clone, Debug, PartialEq)] pub struct Upvalues { - upvalues: Vec, + /// The upvalues of static identifiers. Each static identifier + /// is assigned an integer identifier at compile time, which is + /// an index into this Vec. + static_upvalues: Vec, + + /// The upvalues of dynamic identifiers, if any exist. This + /// consists of the value passed to each enclosing `with val;`, + /// from outermost to innermost. with_stack: Option>, } impl Upvalues { pub fn with_capacity(count: usize) -> Self { Upvalues { - upvalues: Vec::with_capacity(count), + static_upvalues: Vec::with_capacity(count), with_stack: None, } } /// Push an upvalue at the end of the upvalue list. pub fn push(&mut self, value: Value) { - self.upvalues.push(value); + self.static_upvalues.push(value); } /// Set the captured with stack. @@ -53,7 +74,7 @@ impl Index for Upvalues { type Output = Value; fn index(&self, index: UpvalueIdx) -> &Self::Output { - &self.upvalues[index.0] + &self.static_upvalues[index.0] } } @@ -69,13 +90,13 @@ pub trait UpvalueCarrier { /// Read an upvalue at the given index. fn upvalue(&self, idx: UpvalueIdx) -> Ref<'_, Value> { - Ref::map(self.upvalues(), |v| &v.upvalues[idx.0]) + Ref::map(self.upvalues(), |v| &v.static_upvalues[idx.0]) } /// Resolve deferred upvalues from the provided stack slice, /// mutating them in the internal upvalue slots. fn resolve_deferred_upvalues(&self, stack: &[Value]) { - for upvalue in self.upvalues_mut().upvalues.iter_mut() { + for upvalue in self.upvalues_mut().static_upvalues.iter_mut() { if let Value::DeferredUpvalue(idx) = upvalue { *upvalue = stack[idx.0].clone(); } -- cgit 1.4.1