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 <adam@westernsemico.com> Change-Id: If6d0e133292451af906e1c728e34010f99be8c7c Reviewed-on: https://cl.tvl.fyi/c/depot/+/7007 Reviewed-by: j4m3s <james.landrein@gmail.com> Reviewed-by: tazjin <tazjin@tvl.su> Tested-by: BuildkiteCI
This commit is contained in:
parent
13a5e7dd5b
commit
4b01e594d5
1 changed files with 30 additions and 9 deletions
|
@ -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<Value>,
|
||||
/// 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<Value>,
|
||||
|
||||
/// 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<Vec<Value>>,
|
||||
}
|
||||
|
||||
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<UpvalueIdx> 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();
|
||||
}
|
||||
|
|
Loading…
Reference in a new issue