From fd725bc7fdd609a3fcd295966922fb4f5f37f7b9 Mon Sep 17 00:00:00 2001
From: Vincent Ambo <tazjin@tvl.su>
Date: Fri, 3 Nov 2023 11:13:58 +0300
Subject: docs(users/tazjin): add graph explaining tvix-eval Value structure

Change-Id: I436aeba6da6a0d5096452529d7dd0be11a466e8f
Reviewed-on: https://cl.tvl.fyi/c/depot/+/9905
Reviewed-by: tazjin <tazjin@tvl.su>
Tested-by: BuildkiteCI
Autosubmit: tazjin <tazjin@tvl.su>
---
 users/tazjin/tvix-eval-value.d2 | 98 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 users/tazjin/tvix-eval-value.d2

diff --git a/users/tazjin/tvix-eval-value.d2 b/users/tazjin/tvix-eval-value.d2
new file mode 100644
index 000000000000..dad2dbcef2cb
--- /dev/null
+++ b/users/tazjin/tvix-eval-value.d2
@@ -0,0 +1,98 @@
+# D2 diagram of tvix-eval's `Value` type.
+#
+# can be rendered at https://play.d2lang.com/
+#
+# colours have meanings:
+#
+# yellow: recurses
+# orange: heap allocation
+# red: refcount
+#
+# this intentionally does *not* include some internal variants
+
+Value -> Null
+Value -> Bool
+Value -> Integer
+Value -> Float
+
+Box*.style.fill: "lightsalmon"
+Rc*.style.fill: "salmon"
+Vec\<*.style.fill: "salmon"
+
+Value -> String -> NixString -> "Box<str>"
+
+Value -> Path -> "Box<PathBuf>" -> PathBuf
+PathBuf.style.fill: "lightsalmon"
+
+# attribute sets are kinda complicated
+Value -> Attrs -> "Box<NixAttrs>" -> NixAttrs
+NixAttrs -> Empty
+NixAttrs -> KV
+KV.style.fill: "LemonChiffon"
+KV -> Value
+KV -> Value
+NixAttrs -> Map
+Map -> "OrdMap<NixString, Value>" -> "MapEntry<NixString, Value>"
+"OrdMap<NixString, Value>".style.fill: "lightsalmon"
+"MapEntry<NixString, Value>".style.fill: "salmon"
+"MapEntry<NixString, Value>".style.multiple: true
+"MapEntry<NixString, Value>" -> NixString
+"MapEntry<NixString, Value>" -> Value
+"MapEntry<NixString, Value>".style.stroke-width: 15
+"MapEntry<NixString, Value>".style.stroke: "lemonchiffon"
+
+Value -> List -> NixList -> "Rc<imbl::Vector<Value>>"
+"Rc<imbl::Vector<Value>>" -> "VecEntry<Value>" -> Value
+"VecEntry<Value>".style.multiple: true
+"VecEntry<Value>".style.fill: "salmon"
+"VecEntry<Value>".style.stroke-width: 15
+"VecEntry<Value>".style.stroke: "lemonchiffon"
+
+# closures
+
+Value -> Closure -> "Rc<Closure>" -> Closure
+Closure -> "Rc<Lambda>" -> Lambda
+
+Lambda -> Chunk
+Lambda -> SmolStr: sometimes allocates
+SmolStr.style.fill: "lightsalmon"
+Lambda -> usize
+Lambda -> "Option<Formals>" -> Formals
+
+Formals -> "HashMap<NixString, bool>" -> "MapEntry<NixString, bool>"
+"HashMap<NixString, bool>".style.fill: "lightsalmon"
+"MapEntry<NixString, bool>".style.fill: "salmon"
+"MapEntry<NixString, bool>".style.multiple: true
+"MapEntry<NixString, bool>" -> NixString
+
+Closure -> "Rc<Upvalues>" -> Upvalues
+
+Upvalues -> "Vec<Value>"
+"Vec<Value>" -> Value
+"Vec<Value>".style.stroke-width: 15
+"Vec<Value>".style.stroke: "lemonchiffon"
+Upvalues -> "Option<Vec<Value>>"
+"Option<Vec<Value>>" -> Value
+"Option<Vec<Value>>".style.fill: "lightsalmon"
+"Option<Vec<Value>>".style.stroke-width: 15
+"Option<Vec<Value>>".style.stroke: "lemonchiffon"
+
+Value -> Blueprint -> "Rc<Lambda>"
+
+# builtins
+
+Value -> Builtin -> "Box<BuiltinRepr>" -> BuiltinRepr
+BuiltinRepr -> "Rc<dyn BuiltinGen>"
+BuiltinRepr -> "Vec<Value>"
+
+# thunks
+
+Value -> Thunk -> "Rc<RefCell<ThunkRepr>>" -> ThunkRepr
+ThunkRepr -> Suspended
+Suspended -> "Rc<Lambda>"
+Suspended -> "Rc<Upvalues>"
+
+ThunkRepr -> Native -> "Box<dyn Fn() -> Result<Value, ErrorKind>>"
+ThunkRepr -> Blackhole
+ThunkRepr -> Evaluated -> Value
+Evaluated.style.fill: "lemonchiffon"
-- 
cgit 1.4.1