ghc-9.10.3: The GHC API

Safe Haskell | None
Language | GHC2021

GHC.Runtime.Heap.Inspect

Contents

- Entry points and types
- Utils

Synopsis

- cvObtainTerm :: HscEnv -> Int -> Bool -> RttiType -> ForeignHValue -> IO Term
- cvReconstructType :: HscEnv -> Int -> GhciType -> ForeignHValue -> IO (Maybe Type)
- improveRTTIType :: HscEnv -> RttiType -> RttiType -> Maybe Subst
- data Term
  - = Term {
    - ty :: RttiType
    - dc :: Either String DataCon
    - val :: ForeignHValue
    - subTerms :: [Term]
    }
  - | Prim {
    - ty :: RttiType
    - valRaw :: [Word]
    }
  - | Suspension {
    - ctype :: ClosureType
    - ty :: RttiType
    - val :: ForeignHValue
    - bound_to :: Maybe Name
    }
  - | NewtypeWrap {
    - ty :: RttiType
    - dc :: Either String DataCon
    - wrapped_term :: Term
    }
  - | RefWrap {
    - ty :: RttiType
    - wrapped_term :: Term
    }
- isFullyEvaluatedTerm :: Term -> Bool
- termType :: Term -> RttiType
- mapTermType :: (RttiType -> Type) -> Term -> Term
- termTyCoVars :: Term -> TyCoVarSet
- foldTerm :: TermFold a -> Term -> a
- data TermFold a = TermFold {
  - fTerm :: TermProcessor a a
  - fPrim :: RttiType -> [Word] -> a
  - fSuspension :: ClosureType -> RttiType -> ForeignHValue -> Maybe Name -> a
  - fNewtypeWrap :: RttiType -> Either String DataCon -> a -> a
  - fRefWrap :: RttiType -> a -> a
  }
- cPprTerm :: Monad m => CustomTermPrinter m -> Term -> m SDoc
- cPprTermBase :: Monad m => CustomTermPrinter m
- constrClosToName :: HscEnv -> GenClosure a -> IO (Either String Name)

# Entry points and types

cvObtainTerm Source #

Arguments

:: HscEnv |
-> Int | How many times to recurse for subterms
-> Bool | Force thunks
-> RttiType | Type of the object to reconstruct
-> ForeignHValue | Object to reconstruct
-> IO Term |

Term reconstruction

Given a pointer to a heap object (`HValue`) and its type, build a `Term` representation of the object. Subterms (objects in the payload) are also built up to the given `max_depth`. After `max_depth` any subterms will appear as `Suspension`s. Any thunks found while traversing the object will be forced based on `force` parameter.

Types of terms will be refined based on constructors we find during term reconstruction. See `cvReconstructType` for an overview of how type reconstruction works.

cvReconstructType Source #

Arguments

:: HscEnv |
-> Int | How many times to recurse for subterms
-> GhciType | Type to refine
-> ForeignHValue | Refine the type using this value
-> IO (Maybe Type) |

Fast, breadth-first Type reconstruction

Given a heap object (`HValue`) and its (possibly polymorphic) type (usually obtained in GHCi), try to reconstruct a more monomorphic type of the object. This is used for improving type information in debugger. For example, if we have a polymorphic function:

sumNumList :: Num a => [a] -> a sumNumList [] = 0 sumNumList (x : xs) = x + sumList xs

and add a breakpoint to it:

ghci> break sumNumList ghci> sumNumList ([0 .. 9] :: [Int])

ghci shows us more precise types than just `a`s:

Stopped in Main.sumNumList, debugger.hs:3:23-39 _result :: Int = _ x :: Int = 0 xs :: [Int] = _

improveRTTIType :: HscEnv -> RttiType -> RttiType -> Maybe Subst Source #

data Term Source #

Constructors

Term |

Fields

- ty :: RttiType
- dc :: Either String DataCon
- val :: ForeignHValue
- subTerms :: [Term]

Prim |

Fields

- ty :: RttiType
- valRaw :: [Word]

Suspension |

Fields

- ctype :: ClosureType
- ty :: RttiType
- val :: ForeignHValue
- bound_to :: Maybe Name

NewtypeWrap |

Fields

- ty :: RttiType
- dc :: Either String DataCon
- wrapped_term :: Term

RefWrap |

Fields

- ty :: RttiType
- wrapped_term :: Term

#### Instances

Instances details

Outputable Term Source # |
Instance details Defined in GHC.Runtime.Heap.Inspect Methods ppr :: Term -> SDoc Source #

# Utils

isFullyEvaluatedTerm :: Term -> Bool Source #

termType :: Term -> RttiType Source #

mapTermType :: (RttiType -> Type) -> Term -> Term Source #

termTyCoVars :: Term -> TyCoVarSet Source #

foldTerm :: TermFold a -> Term -> a Source #

data TermFold a Source #

Constructors

TermFold |

Fields

- fTerm :: TermProcessor a a
- fPrim :: RttiType -> [Word] -> a
- fSuspension :: ClosureType -> RttiType -> ForeignHValue -> Maybe Name -> a
- fNewtypeWrap :: RttiType -> Either String DataCon -> a -> a
- fRefWrap :: RttiType -> a -> a

cPprTerm :: Monad m => CustomTermPrinter m -> Term -> m SDoc Source #

Takes a list of custom printers with a explicit recursion knot and a term, and returns the output of the first successful printer, or the default printer

cPprTermBase :: Monad m => CustomTermPrinter m Source #

constrClosToName :: HscEnv -> GenClosure a -> IO (Either String Name) Source #