Maintainer	Joachim Breitner <mail@joachim-breitner.de>
Safe Haskell	None

GHC.HeapView

Contents

Heap data types
Reading from the heap
Boxes

Description

With this module, you can investigate the heap representation of Haskell values, i.e. to investigate sharing and lazy evaluation.

Synopsis

Heap data types

data Closure Source

This is the main data type of this module, representing a Haskell value on the heap. This reflects http://hackage.haskell.org/trac/ghc/browser/includes/rts/storage/Closures.h

Constructors

ConsClosure
Fields info :: StgInfoTable ptrArgs :: [Box] dataArgs :: [Word] pkg :: String modl :: String name :: String
ThunkClosure
Fields info :: StgInfoTable ptrArgs :: [Box] dataArgs :: [Word]
SelectorClosure
Fields info :: StgInfoTable selectee :: Box
IndClosure
Fields info :: StgInfoTable indirectee :: Box
BlackholeClosure
Fields info :: StgInfoTable indirectee :: Box
APClosure
Fields info :: StgInfoTable arity :: HalfWord n_args :: HalfWord fun :: Box payload :: [Box]
PAPClosure
Fields info :: StgInfoTable arity :: HalfWord n_args :: HalfWord fun :: Box payload :: [Box]
APStackClosure
Fields info :: StgInfoTable fun :: Box payload :: [Box]
BCOClosure
Fields info :: StgInfoTable instrs :: Box literals :: Box bcoptrs :: Box arity :: HalfWord size :: HalfWord bitmap :: Word
ArrWordsClosure
Fields info :: StgInfoTable bytes :: Word arrWords :: [Word]
MutArrClosure
Fields info :: StgInfoTable mccPtrs :: Word mccSize :: Word mccPayload :: [Box]
MutVarClosure
Fields info :: StgInfoTable var :: Box
MVarClosure
Fields info :: StgInfoTable queueHead :: Box queueTail :: Box value :: Box
FunClosure
Fields info :: StgInfoTable ptrArgs :: [Box] dataArgs :: [Word]
BlockingQueueClosure
Fields info :: StgInfoTable link :: Box blackHole :: Box owner :: Box queue :: Box
OtherClosure
Fields info :: StgInfoTable hvalues :: [Box] rawWords :: [Word]
UnsupportedClosure
Fields info :: StgInfoTable

Instances

Show Closure

allPtrs :: Closure -> [Box]Source

For generic code, this function returns all referenced closures.

data ClosureType Source

A closure type enumeration, in order matching the actual value on the heap. Needs to be synchronized with http://hackage.haskell.org/trac/ghc/browser/includes/rts/storage/ClosureTypes.h

Instances

Enum ClosureType
Eq ClosureType
Ord ClosureType
Show ClosureType

data StgInfoTable Source

This is a somewhat faithful representation of an info table. See http://hackage.haskell.org/trac/ghc/browser/includes/rts/storage/InfoTables.h for more details on this data structure. Note that the Storable instance provided here does _not_ support writing.

Constructors

StgInfoTable
Fields ptrs :: HalfWord nptrs :: HalfWord tipe :: ClosureType srtlen :: HalfWord

Instances

Show StgInfoTable
Storable StgInfoTable

type HalfWord = Word16 Source

Reading from the heap

getClosureData :: a -> IO Closure Source

This function returns parsed heap representation of the argument _at this moment_, even if it is unevaluated or an indirection or other exotic stuff. Beware when passing something to this function, the same caveats as for asBox apply.

getBoxedClosureData :: Box -> IO Closure Source

Like getClosureData, but taking a Box, so it is easier to work with.

getClosureRaw :: a -> IO (Ptr StgInfoTable, [Word], [Box])Source

This returns the raw representation of the given argument. The second component of the triple are the words on the heap, and the third component are those words that are actually pointers. Once back in Haskell word, the Word may be outdated after a garbage collector run, but the corresponding Box will still point to the correct value.

Boxes

data Box Source

An arbitrarily Haskell value in a safe Box. The point is that even unevaluated thunks can safely be moved around inside the Box, and when required, e.g. in getBoxedClosureData, the function knows how far it has to evalue the argument.

Constructors

Box Any

Instances

Eq Box
Show Box

asBox :: a -> Box Source

This takes an arbitrary value and puts it into a box. Note that calls like

 asBox (head list)

will put the thunk "head list" into the box, not the element at the head of the list. For that, use careful case expressions:

 case list of x:_ -> asBox x

INVALID_OBJECT
CONSTR
CONSTR_1_0
CONSTR_0_1
CONSTR_2_0
CONSTR_1_1
CONSTR_0_2
CONSTR_STATIC
CONSTR_NOCAF_STATIC
FUN
FUN_1_0
FUN_0_1
FUN_2_0
FUN_1_1
FUN_0_2
FUN_STATIC
THUNK
THUNK_1_0
THUNK_0_1
THUNK_2_0
THUNK_1_1
THUNK_0_2
THUNK_STATIC
THUNK_SELECTOR
BCO
AP
PAP
AP_STACK
IND
IND_PERM
IND_STATIC
RET_BCO
RET_SMALL
RET_BIG
RET_DYN
RET_FUN
UPDATE_FRAME
CATCH_FRAME
UNDERFLOW_FRAME
STOP_FRAME
BLOCKING_QUEUE
BLACKHOLE
MVAR_CLEAN
MVAR_DIRTY
ARR_WORDS
MUT_ARR_PTRS_CLEAN
MUT_ARR_PTRS_DIRTY
MUT_ARR_PTRS_FROZEN0
MUT_ARR_PTRS_FROZEN
MUT_VAR_CLEAN
MUT_VAR_DIRTY
WEAK
PRIM
MUT_PRIM
TSO
STACK
TREC_CHUNK
ATOMICALLY_FRAME
CATCH_RETRY_FRAME
CATCH_STM_FRAME
WHITEHOLE