GHC.Debug.Client

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 "") g)

Running/Connecting to a debuggee

data Debuggee

type DebugM = DebugM

debuggeeRun

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 :: FilePath -> IO Debuggee

debuggeeClose :: Debuggee -> IO ()

Close the connection to the debuggee.

withDebuggeeRun

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

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

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

Run a DebugM a in the given environment.

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

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

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

Pause/Resume

pause :: Debuggee -> IO ()

Pause the debuggee

fork :: Debuggee -> IO ()

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

resume :: Debuggee -> IO ()

Resume the debuggee

pausePoll :: Debuggee -> IO ()

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

Bracketed version of pause/resume.

Basic Requests

version :: DebugM Version

Query the debuggee for the protocol version

gcRoots :: DebugM [ClosurePtr]

Query the debuggee for the list of GC Roots

allBlocks :: DebugM [RawBlock]

Query the debuggee for all the blocks it knows about

getSourceInfo :: InfoTablePtr -> DebugM (Maybe SourceInformation)

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]

Query the debuggee for the list of saved objects.

precacheBlocks :: DebugM [RawBlock]

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

dereferenceClosure :: ClosurePtr -> DebugM SizedClosure

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

dereferenceToClosurePtr :: SizedClosure -> DebugM SizedClosureP

addConstrDesc :: SizedClosure -> DebugM SizedClosureC

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

dereferenceStack :: StackCont -> DebugM StackFrames

Deference some StackFrames from a given StackCont

dereferencePapPayload :: PayloadCont -> DebugM PapPayload

Derference the PapPayload from the PayloadCont

dereferenceConDesc :: ConstrDescCont -> DebugM ConstrDesc

dereferenceInfoTable :: InfoTablePtr -> DebugM StgInfoTable

dereferenceSRT :: InfoTablePtr -> DebugM SrtPayload

class Quintraversable (m :: TYPE LiftedRep -> TYPE LiftedRep -> TYPE LiftedRep -> TYPE LiftedRep -> TYPE LiftedRep -> TYPE LiftedRep) where

Methods

quintraverse :: Applicative f => (a -> f b) -> (c -> f d) -> (e -> f g) -> (h -> f i) -> (j -> f k) -> m a c e h j -> f (m b d g i k)

Instances

Quintraversable DebugClosure

Defined in GHC.Debug.Types.Closures

Methods

quintraverse :: Applicative f => (a -> f b) -> (c -> f d) -> (e -> f g) -> (h -> f i) -> (j -> f k) -> DebugClosure a c e h j -> f (DebugClosure b d g i k)

Quintraversable (DebugClosureWithExtra x)

Defined in GHC.Debug.Types.Closures

Methods

quintraverse :: Applicative f => (a -> f b) -> (c -> f d) -> (e -> f g) -> (h -> f i) -> (j -> f k) -> DebugClosureWithExtra x a c e h j -> f (DebugClosureWithExtra x b d g i k)

Building a Heap Graph

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

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)

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

The whole graph. The suggested interface is to only use lookupHeapGraph, as the internal representation may change. Nevertheless, we export it here: Sometimes the user knows better what he needs than we do.

Constructors

HeapGraph

Fields

• roots :: !(NonEmpty ClosurePtr)
• graph :: !(IntMap (HeapGraphEntry a))

Instances

Foldable HeapGraph

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

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

Defined in GHC.Debug.Types.Graph

Methods

fmap :: (a -> b) -> HeapGraph a -> HeapGraph b

(<$) :: a -> HeapGraph b -> HeapGraph a

Show a => Show (HeapGraph a)

Defined in GHC.Debug.Types.Graph

Methods

showsPrec :: Int -> HeapGraph a -> ShowS

show :: HeapGraph a -> String

showList :: [HeapGraph a] -> ShowS

data HeapGraphEntry a

For heap graphs, i.e. data structures that also represent sharing and cyclic structures, these are the entries. If the referenced value is Nothing, then we do not have that value in the map, most likely due to exceeding the recursion bound passed to buildHeapGraph.

Besides a pointer to the stored value and the closure representation we have a slot for arbitrary data, for the user's convenience.

Constructors

HeapGraphEntry

Fields

• hgeClosurePtr :: ClosurePtr
• hgeClosure :: DebugClosure SrtHI PapHI ConstrDesc StackHI (Maybe HeapGraphIndex)
• hgeData :: a

Instances

Foldable HeapGraphEntry

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

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

Defined in GHC.Debug.Types.Graph

Methods

fmap :: (a -> b) -> HeapGraphEntry a -> HeapGraphEntry b

(<$) :: a -> HeapGraphEntry b -> HeapGraphEntry a

Show a => Show (HeapGraphEntry a)

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

Pretty-prints a HeapGraph. The resulting string contains newlines. Example for let s = "Ki" in (s, s, cycle "Ho"):

let x1 = "Ki"
    x6 = C# 'H' : C# 'o' : x6
in (x1,x1,x6)

Tracing

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

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

Caching

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

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

Types

module GHC.Debug.Types.Closures

data SourceInformation

Constructors

SourceInformation

Fields

• infoName :: !String
• infoClosureType :: !ClosureType
• infoType :: !String
• infoLabel :: !String
• infoModule :: !String
• infoPosition :: !String

Instances

Show SourceInformation

Defined in GHC.Debug.Types

Methods

showsPrec :: Int -> SourceInformation -> ShowS

show :: SourceInformation -> String

showList :: [SourceInformation] -> ShowS

Eq SourceInformation

Defined in GHC.Debug.Types

Methods

(==) :: SourceInformation -> SourceInformation -> Bool

(/=) :: SourceInformation -> SourceInformation -> Bool

Ord SourceInformation

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

Show RawBlock

Defined in GHC.Debug.Types.Ptr

Methods

showsPrec :: Int -> RawBlock -> ShowS

show :: RawBlock -> String

showList :: [RawBlock] -> ShowS

Binary RawBlock

Defined in GHC.Debug.Types.Ptr

Methods

put :: RawBlock -> Put

get :: Get RawBlock

putList :: [RawBlock] -> Put

data BlockPtr

Instances

Show BlockPtr

Defined in GHC.Debug.Types.Ptr

Methods

showsPrec :: Int -> BlockPtr -> ShowS

show :: BlockPtr -> String

showList :: [BlockPtr] -> ShowS

Binary BlockPtr

Defined in GHC.Debug.Types.Ptr

Methods

put :: BlockPtr -> Put

get :: Get BlockPtr

putList :: [BlockPtr] -> Put

Eq BlockPtr

Defined in GHC.Debug.Types.Ptr

Methods

(==) :: BlockPtr -> BlockPtr -> Bool

(/=) :: BlockPtr -> BlockPtr -> Bool

Ord BlockPtr

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

Defined in GHC.Debug.Types.Ptr

Methods

hashWithSalt :: Int -> BlockPtr -> Int

hash :: BlockPtr -> Int

data StackPtr

Instances

Show StackPtr

Defined in GHC.Debug.Types.Ptr

Methods

showsPrec :: Int -> StackPtr -> ShowS

show :: StackPtr -> String

showList :: [StackPtr] -> ShowS

Binary StackPtr

Defined in GHC.Debug.Types.Ptr

Methods

put :: StackPtr -> Put

get :: Get StackPtr

putList :: [StackPtr] -> Put

Eq StackPtr

Defined in GHC.Debug.Types.Ptr

Methods

(==) :: StackPtr -> StackPtr -> Bool

(/=) :: StackPtr -> StackPtr -> Bool

Ord StackPtr

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

Defined in GHC.Debug.Types.Ptr

Methods

hashWithSalt :: Int -> StackPtr -> Int

hash :: StackPtr -> Int

data ClosurePtr

Instances

Show ClosurePtr

Defined in GHC.Debug.Types.Ptr

Methods

showsPrec :: Int -> ClosurePtr -> ShowS

show :: ClosurePtr -> String

showList :: [ClosurePtr] -> ShowS

Binary ClosurePtr

Defined in GHC.Debug.Types.Ptr

Methods

put :: ClosurePtr -> Put

get :: Get ClosurePtr

putList :: [ClosurePtr] -> Put

Eq ClosurePtr

Defined in GHC.Debug.Types.Ptr

Methods

(==) :: ClosurePtr -> ClosurePtr -> Bool

(/=) :: ClosurePtr -> ClosurePtr -> Bool

Ord ClosurePtr

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

Defined in GHC.Debug.Types.Ptr

Methods

hashWithSalt :: Int -> ClosurePtr -> Int

hash :: ClosurePtr -> Int

data InfoTablePtr

Instances

Show InfoTablePtr

Defined in GHC.Debug.Types.Ptr

Methods

showsPrec :: Int -> InfoTablePtr -> ShowS

show :: InfoTablePtr -> String

showList :: [InfoTablePtr] -> ShowS

Binary InfoTablePtr

Defined in GHC.Debug.Types.Ptr

Methods

put :: InfoTablePtr -> Put

get :: Get InfoTablePtr

putList :: [InfoTablePtr] -> Put

Eq InfoTablePtr

Defined in GHC.Debug.Types.Ptr

Methods

(==) :: InfoTablePtr -> InfoTablePtr -> Bool

(/=) :: InfoTablePtr -> InfoTablePtr -> Bool

Ord InfoTablePtr

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

Defined in GHC.Debug.Types.Ptr

Methods

hashWithSalt :: Int -> InfoTablePtr -> Int

hash :: InfoTablePtr -> Int

type StackHI = GenStackFrames (GenSrtPayload (Maybe HeapGraphIndex)) (Maybe HeapGraphIndex)

type PapHI = GenPapPayload (Maybe HeapGraphIndex)

type HeapGraphIndex = ClosurePtr