Safe Haskell	Safe-Inferred
Language	Haskell2010

GHC.Debug.Client

Contents

Running/Connecting to a debuggee
Running DebugM
Pause/Resume
Basic Requests
Building a Heap Graph
Printing a heap graph
Tracing
Caching
Types

Description

The main API for creating debuggers. For example, this API can be used to connect to an instrumented process, query the GC roots and then decode the first root up to depth 10 and displayed to the user.

main = withDebuggeeConnect "/tmp/ghc-debug" p1

p1 :: Debuggee -> IO ()
p1 e = do
  pause e
  g <- run e $ do
        precacheBlocks
        (r:_) <- gcRoots
        buildHeapGraph (Just 10) r
  putStrLn (ppHeapGraph (const "") h)

Synopsis

data Debuggee
type DebugM = DebugM
debuggeeRun :: FilePath -> FilePath -> IO Debuggee
debuggeeConnect :: FilePath -> IO Debuggee
debuggeeClose :: Debuggee -> IO ()
withDebuggeeRun :: FilePath -> FilePath -> (Debuggee -> IO a) -> IO a
withDebuggeeConnect :: FilePath -> (Debuggee -> IO a) -> IO a
socketDirectory :: IO FilePath
snapshotRun :: FilePath -> (Debuggee -> IO a) -> IO a
run :: Debuggee -> DebugM a -> IO a
runTrace :: Debuggee -> DebugM a -> IO a
runAnalysis :: DebugM a -> (a -> IO r) -> Debuggee -> IO r
pause :: Debuggee -> IO ()
fork :: Debuggee -> IO ()
pauseThen :: Debuggee -> DebugM b -> IO b
resume :: Debuggee -> IO ()
pausePoll :: Debuggee -> IO ()
withPause :: Debuggee -> IO a -> IO a
version :: DebugM Word32
gcRoots :: DebugM [ClosurePtr]
allBlocks :: DebugM [RawBlock]
getSourceInfo :: InfoTablePtr -> DebugM (Maybe SourceInformation)
savedObjects :: DebugM [ClosurePtr]
precacheBlocks :: DebugM [RawBlock]
dereferenceClosure :: ClosurePtr -> DebugM SizedClosure
dereferenceClosures :: [ClosurePtr] -> DebugM [SizedClosure]
dereferenceStack :: StackCont -> DebugM StackFrames
dereferencePapPayload :: PayloadCont -> DebugM PapPayload
dereferenceConDesc :: ConstrDescCont -> DebugM ConstrDesc
dereferenceInfoTable :: InfoTablePtr -> DebugM StgInfoTable
class Quadtraversable (m :: TYPE LiftedRep -> TYPE LiftedRep -> TYPE LiftedRep -> TYPE LiftedRep -> TYPE LiftedRep) where
- quadtraverse :: Applicative f => (a -> f b) -> (c -> f d) -> (e -> f g) -> (h -> f i) -> m a c e h -> f (m b d g i)
buildHeapGraph :: Maybe Int -> ClosurePtr -> DebugM (HeapGraph Size)
multiBuildHeapGraph :: Maybe Int -> NonEmpty ClosurePtr -> DebugM (HeapGraph Size)
data HeapGraph a = HeapGraph {
- roots :: !(NonEmpty ClosurePtr)
- graph :: !(IntMap (HeapGraphEntry a))
}
data HeapGraphEntry a = HeapGraphEntry {
- hgeClosurePtr :: ClosurePtr
- hgeClosure :: DebugClosure PapHI ConstrDesc StackHI (Maybe HeapGraphIndex)
- hgeData :: a
}
ppHeapGraph :: (a -> String) -> HeapGraph a -> String
traceWrite :: DebugMonad m => Show a => a -> m ()
traceMsg :: DebugMonad m => String -> m ()
saveCache :: DebugMonad m => FilePath -> m ()
loadCache :: DebugMonad m => FilePath -> m ()
data SourceInformation = SourceInformation {
- infoName :: !String
- infoClosureType :: !ClosureType
- infoType :: !String
- infoLabel :: !String
- infoModule :: !String
- infoPosition :: !String
}
data RawBlock = RawBlock BlockPtr Word16 ByteString
data BlockPtr
data StackPtr
data ClosurePtr
data InfoTablePtr
type StackHI = GenStackFrames (Maybe HeapGraphIndex)
type PapHI = GenPapPayload (Maybe HeapGraphIndex)
type HeapGraphIndex = ClosurePtr

Running/Connecting to a debuggee

data Debuggee Source #

type DebugM = DebugM Source #

debuggeeRun Source #

Arguments

:: FilePath	path to executable to run as the debuggee
-> FilePath	filename of socket (e.g. `"/tmp/ghc-debug"`)
-> IO Debuggee

Run a debuggee and connect to it. Use debuggeeClose when you're done.

debuggeeConnect Source #

Arguments

:: FilePath	filename of socket (e.g. `"/tmp/ghc-debug"`)
-> IO Debuggee

Connect to a debuggee on the given socket. Use debuggeeClose when you're done.

debuggeeClose :: Debuggee -> IO () Source #

Close the connection to the debuggee.

withDebuggeeRun Source #

Arguments

:: FilePath	path to executable to run as the debuggee
-> FilePath	filename of socket (e.g. `"/tmp/ghc-debug"`)
-> (Debuggee -> IO a)
-> IO a

Bracketed version of debuggeeRun. Runs a debuggee, connects to it, runs the action, kills the process, then closes the debuggee.

withDebuggeeConnect Source #

Arguments

:: FilePath	filename of socket (e.g. `"/tmp/ghc-debug"`)
-> (Debuggee -> IO a)
-> IO a

Bracketed version of debuggeeConnect. Connects to a debuggee, runs the action, then closes the debuggee.

socketDirectory :: IO FilePath #

snapshotRun :: FilePath -> (Debuggee -> IO a) -> IO a Source #

Start an analysis session using a snapshot. This will not connect to a debuggee. The snapshot is created by snapshot.

Running DebugM

run :: Debuggee -> DebugM a -> IO a Source #

Run a DebugM a in the given environment.

runTrace :: Debuggee -> DebugM a -> IO a Source #

runAnalysis :: DebugM a -> (a -> IO r) -> Debuggee -> IO r Source #

Perform the given analysis whilst the debuggee is paused, then resume and apply the continuation to the result.

Pause/Resume

pause :: Debuggee -> IO () Source #

Pause the debuggee

fork :: Debuggee -> IO () Source #

pauseThen :: Debuggee -> DebugM b -> IO b Source #

resume :: Debuggee -> IO () Source #

Resume the debuggee

pausePoll :: Debuggee -> IO () Source #

Like pause, but wait for the debuggee to pause itself. It currently impossible to resume after a pause caused by a poll.?????????? Is that true???? can we not just call resume????

withPause :: Debuggee -> IO a -> IO a Source #

Bracketed version of pause/resume.

Basic Requests

version :: DebugM Word32 Source #

Query the debuggee for the protocol version

gcRoots :: DebugM [ClosurePtr] Source #

Query the debuggee for the list of GC Roots

allBlocks :: DebugM [RawBlock] Source #

Query the debuggee for all the blocks it knows about

getSourceInfo :: InfoTablePtr -> DebugM (Maybe SourceInformation) Source #

Query the debuggee for source information about a specific info table. This requires your executable to be built with -finfo-table-map.

savedObjects :: DebugM [ClosurePtr] Source #

Query the debuggee for the list of saved objects.

precacheBlocks :: DebugM [RawBlock] Source #

Fetch all the blocks from the debuggee and add them to the block cache

dereferenceClosure :: ClosurePtr -> DebugM SizedClosure Source #

Consult the BlockCache for the block which contains a specific closure, if it's not there then try to fetch the right block, if that fails, call dereferenceClosureDirect

dereferenceClosures :: [ClosurePtr] -> DebugM [SizedClosure] Source #

dereferenceStack :: StackCont -> DebugM StackFrames Source #

Deference some StackFrames from a given StackCont

dereferencePapPayload :: PayloadCont -> DebugM PapPayload Source #

Derference the PapPayload from the PayloadCont

dereferenceConDesc :: ConstrDescCont -> DebugM ConstrDesc Source #

dereferenceInfoTable :: InfoTablePtr -> DebugM StgInfoTable Source #

class Quadtraversable (m :: TYPE LiftedRep -> TYPE LiftedRep -> TYPE LiftedRep -> TYPE LiftedRep -> TYPE LiftedRep) where #

Methods

quadtraverse :: Applicative f => (a -> f b) -> (c -> f d) -> (e -> f g) -> (h -> f i) -> m a c e h -> f (m b d g i) #

Instances

Instances details

Quadtraversable DebugClosure
Instance details Defined in GHC.Debug.Types.Closures Methods quadtraverse :: Applicative f => (a -> f b) -> (c -> f d) -> (e -> f g) -> (h -> f i) -> DebugClosure a c e h -> f (DebugClosure b d g i) #
Quadtraversable (DebugClosureWithExtra x)
Instance details Defined in GHC.Debug.Types.Closures Methods quadtraverse :: Applicative f => (a -> f b) -> (c -> f d) -> (e -> f g) -> (h -> f i) -> DebugClosureWithExtra x a c e h -> f (DebugClosureWithExtra x b d g i) #

Building a Heap Graph

buildHeapGraph :: Maybe Int -> ClosurePtr -> DebugM (HeapGraph Size) Source #

Build a heap graph starting from the given root. The first argument controls how many levels to recurse. You nearly always want to set this to a small number ~ 10, as otherwise you can easily run out of memory.

multiBuildHeapGraph :: Maybe Int -> NonEmpty ClosurePtr -> DebugM (HeapGraph Size) Source #

Build a heap graph starting from multiple roots. The first argument controls how many levels to recurse. You nearly always want to set this value to a small number ~ 10 as otherwise you can easily run out of memory.

data HeapGraph a #

Constructors

HeapGraph
Fields roots :: !(NonEmpty ClosurePtr) graph :: !(IntMap (HeapGraphEntry a))

Instances

Instances details

Foldable HeapGraph
Instance details Defined in GHC.Debug.Types.Graph Methods fold :: Monoid m => HeapGraph m -> m # foldMap :: Monoid m => (a -> m) -> HeapGraph a -> m # foldMap' :: Monoid m => (a -> m) -> HeapGraph a -> m # foldr :: (a -> b -> b) -> b -> HeapGraph a -> b # foldr' :: (a -> b -> b) -> b -> HeapGraph a -> b # foldl :: (b -> a -> b) -> b -> HeapGraph a -> b # foldl' :: (b -> a -> b) -> b -> HeapGraph a -> b # foldr1 :: (a -> a -> a) -> HeapGraph a -> a # foldl1 :: (a -> a -> a) -> HeapGraph a -> a # toList :: HeapGraph a -> [a] # null :: HeapGraph a -> Bool # length :: HeapGraph a -> Int # elem :: Eq a => a -> HeapGraph a -> Bool # maximum :: Ord a => HeapGraph a -> a # minimum :: Ord a => HeapGraph a -> a # sum :: Num a => HeapGraph a -> a # product :: Num a => HeapGraph a -> a #
Traversable HeapGraph
Instance details Defined in GHC.Debug.Types.Graph Methods traverse :: Applicative f => (a -> f b) -> HeapGraph a -> f (HeapGraph b) # sequenceA :: Applicative f => HeapGraph (f a) -> f (HeapGraph a) # mapM :: Monad m => (a -> m b) -> HeapGraph a -> m (HeapGraph b) # sequence :: Monad m => HeapGraph (m a) -> m (HeapGraph a) #
Functor HeapGraph
Instance details Defined in GHC.Debug.Types.Graph Methods fmap :: (a -> b) -> HeapGraph a -> HeapGraph b # (<$) :: a -> HeapGraph b -> HeapGraph a #
Show a => Show (HeapGraph a)
Instance details Defined in GHC.Debug.Types.Graph Methods showsPrec :: Int -> HeapGraph a -> ShowS # show :: HeapGraph a -> String # showList :: [HeapGraph a] -> ShowS #

data HeapGraphEntry a #

Constructors

HeapGraphEntry
Fields hgeClosurePtr :: ClosurePtr hgeClosure :: DebugClosure PapHI ConstrDesc StackHI (Maybe HeapGraphIndex) hgeData :: a

Instances

Instances details

Foldable HeapGraphEntry
Instance details Defined in GHC.Debug.Types.Graph Methods fold :: Monoid m => HeapGraphEntry m -> m # foldMap :: Monoid m => (a -> m) -> HeapGraphEntry a -> m # foldMap' :: Monoid m => (a -> m) -> HeapGraphEntry a -> m # foldr :: (a -> b -> b) -> b -> HeapGraphEntry a -> b # foldr' :: (a -> b -> b) -> b -> HeapGraphEntry a -> b # foldl :: (b -> a -> b) -> b -> HeapGraphEntry a -> b # foldl' :: (b -> a -> b) -> b -> HeapGraphEntry a -> b # foldr1 :: (a -> a -> a) -> HeapGraphEntry a -> a # foldl1 :: (a -> a -> a) -> HeapGraphEntry a -> a # toList :: HeapGraphEntry a -> [a] # null :: HeapGraphEntry a -> Bool # length :: HeapGraphEntry a -> Int # elem :: Eq a => a -> HeapGraphEntry a -> Bool # maximum :: Ord a => HeapGraphEntry a -> a # minimum :: Ord a => HeapGraphEntry a -> a # sum :: Num a => HeapGraphEntry a -> a # product :: Num a => HeapGraphEntry a -> a #
Traversable HeapGraphEntry
Instance details Defined in GHC.Debug.Types.Graph Methods traverse :: Applicative f => (a -> f b) -> HeapGraphEntry a -> f (HeapGraphEntry b) # sequenceA :: Applicative f => HeapGraphEntry (f a) -> f (HeapGraphEntry a) # mapM :: Monad m => (a -> m b) -> HeapGraphEntry a -> m (HeapGraphEntry b) # sequence :: Monad m => HeapGraphEntry (m a) -> m (HeapGraphEntry a) #
Functor HeapGraphEntry
Instance details Defined in GHC.Debug.Types.Graph Methods fmap :: (a -> b) -> HeapGraphEntry a -> HeapGraphEntry b # (<$) :: a -> HeapGraphEntry b -> HeapGraphEntry a #
Show a => Show (HeapGraphEntry a)
Instance details Defined in GHC.Debug.Types.Graph Methods showsPrec :: Int -> HeapGraphEntry a -> ShowS # show :: HeapGraphEntry a -> String # showList :: [HeapGraphEntry a] -> ShowS #

Printing a heap graph

ppHeapGraph :: (a -> String) -> HeapGraph a -> String #

Tracing

traceWrite :: DebugMonad m => Show a => a -> m () Source #

traceMsg :: DebugMonad m => String -> m () Source #

Caching

saveCache :: DebugMonad m => FilePath -> m () Source #

loadCache :: DebugMonad m => FilePath -> m () Source #

Types

data SourceInformation #

Constructors

SourceInformation
Fields infoName :: !String infoClosureType :: !ClosureType infoType :: !String infoLabel :: !String infoModule :: !String infoPosition :: !String

Instances

Instances details

Show SourceInformation
Instance details Defined in GHC.Debug.Types Methods showsPrec :: Int -> SourceInformation -> ShowS # show :: SourceInformation -> String # showList :: [SourceInformation] -> ShowS #
Eq SourceInformation
Instance details Defined in GHC.Debug.Types Methods (==) :: SourceInformation -> SourceInformation -> Bool # (/=) :: SourceInformation -> SourceInformation -> Bool #
Ord SourceInformation
Instance details Defined in GHC.Debug.Types Methods compare :: SourceInformation -> SourceInformation -> Ordering # (<) :: SourceInformation -> SourceInformation -> Bool # (<=) :: SourceInformation -> SourceInformation -> Bool # (>) :: SourceInformation -> SourceInformation -> Bool # (>=) :: SourceInformation -> SourceInformation -> Bool # max :: SourceInformation -> SourceInformation -> SourceInformation # min :: SourceInformation -> SourceInformation -> SourceInformation #

data RawBlock #

Constructors

RawBlock BlockPtr Word16 ByteString

Instances

Instances details

Show RawBlock
Instance details Defined in GHC.Debug.Types.Ptr Methods showsPrec :: Int -> RawBlock -> ShowS # show :: RawBlock -> String # showList :: [RawBlock] -> ShowS #
Binary RawBlock
Instance details Defined in GHC.Debug.Types.Ptr Methods put :: RawBlock -> Put # get :: Get RawBlock # putList :: [RawBlock] -> Put #

data BlockPtr #

Instances

Instances details

Show BlockPtr
Instance details Defined in GHC.Debug.Types.Ptr Methods showsPrec :: Int -> BlockPtr -> ShowS # show :: BlockPtr -> String # showList :: [BlockPtr] -> ShowS #
Binary BlockPtr
Instance details Defined in GHC.Debug.Types.Ptr Methods put :: BlockPtr -> Put # get :: Get BlockPtr # putList :: [BlockPtr] -> Put #
Eq BlockPtr
Instance details Defined in GHC.Debug.Types.Ptr Methods (==) :: BlockPtr -> BlockPtr -> Bool # (/=) :: BlockPtr -> BlockPtr -> Bool #
Ord BlockPtr
Instance details Defined in GHC.Debug.Types.Ptr Methods compare :: BlockPtr -> BlockPtr -> Ordering # (<) :: BlockPtr -> BlockPtr -> Bool # (<=) :: BlockPtr -> BlockPtr -> Bool # (>) :: BlockPtr -> BlockPtr -> Bool # (>=) :: BlockPtr -> BlockPtr -> Bool # max :: BlockPtr -> BlockPtr -> BlockPtr # min :: BlockPtr -> BlockPtr -> BlockPtr #
Hashable BlockPtr
Instance details Defined in GHC.Debug.Types.Ptr Methods hashWithSalt :: Int -> BlockPtr -> Int # hash :: BlockPtr -> Int #

data StackPtr #

Instances

Instances details

Show StackPtr
Instance details Defined in GHC.Debug.Types.Ptr Methods showsPrec :: Int -> StackPtr -> ShowS # show :: StackPtr -> String # showList :: [StackPtr] -> ShowS #
Binary StackPtr
Instance details Defined in GHC.Debug.Types.Ptr Methods put :: StackPtr -> Put # get :: Get StackPtr # putList :: [StackPtr] -> Put #
Eq StackPtr
Instance details Defined in GHC.Debug.Types.Ptr Methods (==) :: StackPtr -> StackPtr -> Bool # (/=) :: StackPtr -> StackPtr -> Bool #
Ord StackPtr
Instance details Defined in GHC.Debug.Types.Ptr Methods compare :: StackPtr -> StackPtr -> Ordering # (<) :: StackPtr -> StackPtr -> Bool # (<=) :: StackPtr -> StackPtr -> Bool # (>) :: StackPtr -> StackPtr -> Bool # (>=) :: StackPtr -> StackPtr -> Bool # max :: StackPtr -> StackPtr -> StackPtr # min :: StackPtr -> StackPtr -> StackPtr #
Hashable StackPtr
Instance details Defined in GHC.Debug.Types.Ptr Methods hashWithSalt :: Int -> StackPtr -> Int # hash :: StackPtr -> Int #

data ClosurePtr #

Instances

Instances details

Show ClosurePtr
Instance details Defined in GHC.Debug.Types.Ptr Methods showsPrec :: Int -> ClosurePtr -> ShowS # show :: ClosurePtr -> String # showList :: [ClosurePtr] -> ShowS #
Binary ClosurePtr
Instance details Defined in GHC.Debug.Types.Ptr Methods put :: ClosurePtr -> Put # get :: Get ClosurePtr # putList :: [ClosurePtr] -> Put #
Eq ClosurePtr
Instance details Defined in GHC.Debug.Types.Ptr Methods (==) :: ClosurePtr -> ClosurePtr -> Bool # (/=) :: ClosurePtr -> ClosurePtr -> Bool #
Ord ClosurePtr
Instance details Defined in GHC.Debug.Types.Ptr Methods compare :: ClosurePtr -> ClosurePtr -> Ordering # (<) :: ClosurePtr -> ClosurePtr -> Bool # (<=) :: ClosurePtr -> ClosurePtr -> Bool # (>) :: ClosurePtr -> ClosurePtr -> Bool # (>=) :: ClosurePtr -> ClosurePtr -> Bool # max :: ClosurePtr -> ClosurePtr -> ClosurePtr # min :: ClosurePtr -> ClosurePtr -> ClosurePtr #
Hashable ClosurePtr
Instance details Defined in GHC.Debug.Types.Ptr Methods hashWithSalt :: Int -> ClosurePtr -> Int # hash :: ClosurePtr -> Int #

data InfoTablePtr #

Instances

Instances details

Show InfoTablePtr
Instance details Defined in GHC.Debug.Types.Ptr Methods showsPrec :: Int -> InfoTablePtr -> ShowS # show :: InfoTablePtr -> String # showList :: [InfoTablePtr] -> ShowS #
Binary InfoTablePtr
Instance details Defined in GHC.Debug.Types.Ptr Methods put :: InfoTablePtr -> Put # get :: Get InfoTablePtr # putList :: [InfoTablePtr] -> Put #
Eq InfoTablePtr
Instance details Defined in GHC.Debug.Types.Ptr Methods (==) :: InfoTablePtr -> InfoTablePtr -> Bool # (/=) :: InfoTablePtr -> InfoTablePtr -> Bool #
Ord InfoTablePtr
Instance details Defined in GHC.Debug.Types.Ptr Methods compare :: InfoTablePtr -> InfoTablePtr -> Ordering # (<) :: InfoTablePtr -> InfoTablePtr -> Bool # (<=) :: InfoTablePtr -> InfoTablePtr -> Bool # (>) :: InfoTablePtr -> InfoTablePtr -> Bool # (>=) :: InfoTablePtr -> InfoTablePtr -> Bool # max :: InfoTablePtr -> InfoTablePtr -> InfoTablePtr # min :: InfoTablePtr -> InfoTablePtr -> InfoTablePtr #
Hashable InfoTablePtr
Instance details Defined in GHC.Debug.Types.Ptr Methods hashWithSalt :: Int -> InfoTablePtr -> Int # hash :: InfoTablePtr -> Int #

type StackHI = GenStackFrames (Maybe HeapGraphIndex) #

type PapHI = GenPapPayload (Maybe HeapGraphIndex) #

type HeapGraphIndex = ClosurePtr #