[GHC] #8864: Document heap allocation functions in StgCmmMonad/StgCmmLayout
#8864: Document heap allocation functions in StgCmmMonad/StgCmmLayout ------------------------------------+------------------------------------- Reporter: tibbe | Owner: Type: feature request | Status: new Priority: normal | Milestone: Component: Documentation | Version: 7.6.3 Keywords: | Operating System: Unknown/Multiple Architecture: Unknown/Multiple | Type of failure: None/Unknown Difficulty: Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | ------------------------------------+------------------------------------- I'm having a hard time using the heap allocation functions in `StgCmmMonad` and `StgCmmLayout`, as they lack documentation. I'd be very grateful if someone could at least document: * `getHpRelOffset` * `setVirtHp` * `getVirtHp` To get an idea which questions I'm struggling with, I need to e.g. understand if the value returned by `getHpRelOffset` is affected by later calls to `setVirtHp`. This is probably obvious to some, but reading the code alone is not enough to get a good understanding how all the heap allocation code hangs together. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/8864 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#8864: Document heap allocation functions in StgCmmMonad/StgCmmLayout -------------------------------------+------------------------------------ Reporter: tibbe | Owner: Type: feature request | Status: new Priority: normal | Milestone: Component: Documentation | Version: 7.6.3 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: Unknown/Multiple Type of failure: None/Unknown | Difficulty: Unknown Test Case: | Blocked By: Blocking: | Related Tickets: -------------------------------------+------------------------------------ Comment (by tibbe): Another question to help the documentation effort along: which functions change the real `Hp`? Knowing that would allow the programmer to reason about how long the value (a `CmmExpr`) returned by `getHpRelOffset` is valid. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/8864#comment:1 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#8864: Document heap allocation functions in StgCmmMonad/StgCmmLayout -------------------------------------+------------------------------------ Reporter: tibbe | Owner: Type: feature request | Status: new Priority: normal | Milestone: Component: Documentation | Version: 7.6.3 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: Unknown/Multiple Type of failure: None/Unknown | Difficulty: Unknown Test Case: | Blocked By: Blocking: | Related Tickets: -------------------------------------+------------------------------------ Comment (by tibbe): Perhaps the writing from http://blog.ezyang.com/2013/09/of-monadic- fixpoints-and-heap-offsets/ could be integrated into the Haddocks? Having tutorial style material "to the side" is great, but GHC could use more API docs to make it more accessible. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/8864#comment:2 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#8864: Document heap allocation functions in StgCmmMonad/StgCmmLayout -------------------------------------+------------------------------------ Reporter: tibbe | Owner: Type: feature request | Status: new Priority: normal | Milestone: Component: Documentation | Version: 7.6.3 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: Unknown/Multiple Type of failure: None/Unknown | Difficulty: Unknown Test Case: | Blocked By: Blocking: | Related Tickets: -------------------------------------+------------------------------------ Comment (by simonpj): I've added this to `StgCmmMonad`: {{{ {- Note [Virtual and real heap pointers] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The code generator can allocate one or more objects contiguously, performing one heap check to cover allocation of all the objects at once. Let's call this little chunk of heap space an "allocation chunk". The code generator will emit code to * Perform a heap-exhaustion check * Move the heap pointer to the end of the allocation chunk * Allocate multiple objects within the chunk The code generator uses VirtualHpOffsets to address words within a single allocation chunk; these start at one and increase positively. The first word of the chunk has VirtualHpOffset=1, the second has VirtualHpOffset=2, and so on. * The field realHp tracks (the VirtualHpOffset) where the real Hp register is pointing. Typically it'll be pointing to the end of the allocation chunk. * The field virtHp gives the VirtualHpOffset of the highest-allocated word so far. It starts at zero (meaning no word has been allocated), and increases whenever an object is allocated. The difference between realHp and virtHp gives the offset from the real Hp register of a particular word in the allocation chunk. This is what getHpRelOffset does. }}} Does that help? If not, how can I clarify further? -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/8864#comment:3 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#8864: Document heap allocation functions in StgCmmMonad/StgCmmLayout -------------------------------------+------------------------------------ Reporter: tibbe | Owner: Type: feature request | Status: new Priority: normal | Milestone: Component: Documentation | Version: 7.6.3 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: Unknown/Multiple Type of failure: None/Unknown | Difficulty: Unknown Test Case: | Blocked By: Blocking: | Related Tickets: -------------------------------------+------------------------------------ Comment (by tibbe): That does help. Clarifying the invariants (e.g. when does a value returned by `getHpRelOffset` become invalid) would also help. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/8864#comment:4 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#8864: Document heap allocation functions in StgCmmMonad/StgCmmLayout -------------------------------------+------------------------------------ Reporter: tibbe | Owner: Type: feature request | Status: new Priority: normal | Milestone: Component: Documentation | Version: 7.6.3 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: Unknown/Multiple Type of failure: None/Unknown | Difficulty: Unknown Test Case: | Blocked By: Blocking: | Related Tickets: -------------------------------------+------------------------------------ Comment (by simonpj): It's never invalid, so far as I know. Simon -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/8864#comment:5 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#8864: Document heap allocation functions in StgCmmMonad/StgCmmLayout -------------------------------------+------------------------------------ Reporter: tibbe | Owner: Type: feature request | Status: new Priority: normal | Milestone: Component: Documentation | Version: 7.6.3 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: Unknown/Multiple Type of failure: None/Unknown | Difficulty: Unknown Test Case: | Blocked By: Blocking: | Related Tickets: -------------------------------------+------------------------------------ Comment (by tibbe): Replying to [comment:5 simonpj]:
It's never invalid, so far as I know.
I think it's invalid as soon as Hp changes. See this comment: https://github.com/ghc/ghc/blob/master/compiler/codeGen/StgCmmHeap.hs#L80 -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/8864#comment:6 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#8864: Document heap allocation functions in StgCmmMonad/StgCmmLayout -------------------------------------+------------------------------------ Reporter: tibbe | Owner: Type: feature request | Status: new Priority: normal | Milestone: Component: Documentation | Version: 7.6.3 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: Unknown/Multiple Type of failure: None/Unknown | Difficulty: Unknown Test Case: | Blocked By: Blocking: | Related Tickets: -------------------------------------+------------------------------------ Comment (by simonpj): Ah yes, now I see. You are right: the offset returned is valid only until the real heap pointer is moved. `virtHp` doesn't matter. I'll add that. Simon -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/8864#comment:7 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#8864: Document heap allocation functions in StgCmmMonad/StgCmmLayout
-------------------------------------+------------------------------------
Reporter: tibbe | Owner:
Type: feature request | Status: new
Priority: normal | Milestone:
Component: Documentation | Version: 7.6.3
Resolution: | Keywords:
Operating System: Unknown/Multiple | Architecture: Unknown/Multiple
Type of failure: None/Unknown | Difficulty: Unknown
Test Case: | Blocked By:
Blocking: | Related Tickets:
-------------------------------------+------------------------------------
Comment (by Simon Peyton Jones
#8864: Document heap allocation functions in StgCmmMonad/StgCmmLayout -------------------------------------+------------------------------------ Reporter: tibbe | Owner: Type: feature request | Status: closed Priority: normal | Milestone: Component: Documentation | Version: 7.6.3 Resolution: fixed | Keywords: Operating System: Unknown/Multiple | Architecture: Unknown/Multiple Type of failure: None/Unknown | Difficulty: Unknown Test Case: | Blocked By: Blocking: | Related Tickets: -------------------------------------+------------------------------------ Changes (by simonpj): * status: new => closed * resolution: => fixed -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/8864#comment:9 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
participants (1)
-
GHC