[Git][ghc/ghc][wip/decode_cloned_stack] Overhaul note

[Sven Tennie (@supersven)]

Sven Tennie pushed to branch wip/decode_cloned_stack at Glasgow Haskell Compiler / GHC


Commits:
08a739eb by Sven Tennie at 2023-02-21T11:52:26+00:00
Overhaul note

- - - - -


1 changed file:

- libraries/ghc-heap/GHC/Exts/Stack/Decode.hs


Changes:

=====================================
libraries/ghc-heap/GHC/Exts/Stack/Decode.hs
=====================================
@@ -52,23 +52,34 @@ the same. (Though, the absolute addresses change!)
 Stack frame iterator
 ====================
 
-A stack frame interator (StackFrameIter) consists of a StackSnapshot# and a
-relative offset into the the array of stack frames (StgStack->stack). The
-StackSnapshot# represents a StgStack closure. It is updated by the garbage
-collector when the stack closure is moved.
+A stack frame iterator (StackFrameIter) deals with the mentioned challenges
+regarding garbage collected memory. It consists of the StgStack itself and the
+mentioned offset (or index) where needed.
 
-The relative offset describes the location of a stack frame. As stack frames
-come in various sizes, one cannot simply step over the stack array with a
-constant offset.
+It has three constructors:
 
-The head of the stack frame array has offset 0. To traverse the stack frames the
-latest stack frame's offset is incremented by the closure size. The unit of the
-offset is machine words (32bit or 64bit).
+- SfiStackClosure: Represents the StgStack closure itself. As stacks are chained
+  by underflow frames, there can be multiple StgStack closures per logical
+  stack.
 
-Additionally, StackFrameIter contains a flag (isPrimitive) to indicate if a
-location on the stack should be interpreted as plain data word (in contrast to
-being a closure or a pointer to a closure.) It's used when bitmap encoded
-arguments are interpreted.
+- SfiClosure: Represents a closure on the stack. The location on the stack is
+  defined by the StgStack itself and an index into it.
+
+- SfiPrimitive: Is structurally equivalent to SfiClosure, but represents a data
+  Word on the stack. These appear as payloads to closures with bitmap layout.
+  From the RTS-perspective, there's no information about the concrete type of
+  the Word. So, it's just handled as Word in further processing.
+
+The `stackSnapshot# :: !StackSnapshot#` field represents a StgStack closure. It
+is updated by the garbage collector when the stack closure is moved.
+
+The relative offset (index) describes the location of a stack frame on the
+stack. As stack frames come in various sizes, one cannot simply step over the
+stack array with a constant offset.
+
+The head of the stack frame array has offset (index) 0. To traverse the stack
+frames the latest stack frame's offset is incremented by the closure size. The
+unit of the offset is machine words (32bit or 64bit.)
 
 Boxes
 =====
@@ -78,7 +89,7 @@ creating a Box with a pointer (address) to a stack frame would break as soon as
 the StgStack closure is moved.
 
 To deal with this another kind of Box is introduced: A StackFrameBox contains a
-stack frame iterator for a decoded stack frame or it's payload.
+stack frame iterator (StackFrameIter).
 
 Heap-represented closures referenced by stack frames are boxed the usual way,
 with a Box that contains a pointer to the closure as it's payload. In
@@ -446,4 +457,5 @@ decodeStack' s =
 
 #else
 module GHC.Exts.Stack.Decode where
+import GHC.Data.UnionFind (equivalent)
 #endif



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/08a739eb73778919d7aaa2a32dfa71a1953fdeb4

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/08a739eb73778919d7aaa2a32dfa71a1953fdeb4
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20230221/e9567cc4/attachment-0001.html>