Safe Haskell	None
Language	GHC2021

GHC.Debugger.Monad

Contents

Finding Debugger View
Modules
Forcing laziness

Synopsis

newtype Debugger a = Debugger {
- unDebugger :: ReaderT DebuggerState Ghc a
}
data BreakpointInfo = BreakpointInfo {
- bpInfoStatus :: !BreakpointStatus
- bpInfoKind :: !BreakpointKind
- bpInfoAction :: !BreakpointAction
}
data DebuggerState = DebuggerState {
- activeBreakpoints :: IORef (BreakpointMap BreakpointInfo)
- rtinstancesCache :: IORef RuntimeInstancesCache
- threadMap :: IORef ThreadMap
- compCache :: IORef CompCache
- hsDbgViewUnitId :: Maybe UnitId
- dbgLogger :: LogAction Debugger DebuggerLog
}
data BreakpointStatus
- = BreakpointDisabled
- | BreakpointEnabled
- | BreakpointAfterCount Int
- | BreakpointWhenCond String
- | BreakpointAfterCountCond Int String
data BreakpointAction
- = BreakpointStop
- | BreakpointLogAndResume String
data RunDebuggerSettings = RunDebuggerSettings {
- supportsANSIStyling :: Bool
- supportsANSIHyperlinks :: Bool
- interpreterSettings :: InterpreterSettings
}
runDebugger :: LogAction IO DebuggerLog -> DebugRunner Ghc a -> RunDebuggerSettings -> Debugger a -> IO a
type DebugSession (m :: Type -> Type) a = FilePath -> [String] -> m () -> Ghc a
type DebugRunner (m :: Type -> Type) a = DebugSession m a -> IO a
data ProjectDebugSpec = ProjectDebugSpec {
- rootDir :: FilePath
- componentDir :: FilePath
- libdir :: FilePath
- units :: [String]
- ghcInvocation :: [String]
- absEntryFile :: FilePath
- extraGhcArgs :: [String]
}
withProjectDebugSession :: GhcMonad m => ProjectDebugSpec -> DebugRunner m a
runDebuggerAction :: LogAction IO DebuggerLog -> FilePath -> [String] -> RunDebuggerSettings -> Ghc () -> Debugger a -> Ghc a
preservingThreadLabel :: HasCallStack => Ghc a -> Ghc a
loadInternal :: LogAction IO DebuggerLog -> Ways -> Ghc ()
data FailedToLoadFFIInspectModule = FailedToLoadFFIInspectModule
loadFFIInspect :: LogAction IO DebuggerLog -> Ways -> Ghc ()
findOrLoadHaskellDebuggerView :: LogAction IO DebuggerLog -> Ways -> Ghc (UnitId, [ModuleName])
cleanupInterp :: Ghc ()
annotateDebuggerStackString :: String -> Debugger a -> Debugger a
parseDynamicFlagsWithRootDir :: MonadIO m => FilePath -> Logger -> DynFlags -> [Located String] -> m (DynFlags, [Located String], Messages DriverMessage)
doDownsweep :: GhcMonad m => Maybe ModuleGraph -> m ModuleGraph
doLoad :: GhcMonad m => Maybe ModIfaceCache -> LoadHowMuch -> ModuleGraph -> m SuccessFlag
loadInMemoryModules :: LogAction IO DebuggerLog -> UnitId -> [(ModuleName, StringBuffer)] -> Ghc [SuccessFlag]
getHsDebuggerViewUid :: Debugger (Maybe UnitId)
findHsDebuggerViewUnitId :: Ghc (Maybe UnitId)
initialDebuggerState :: LogAction Debugger DebuggerLog -> Maybe UnitId -> Ghc DebuggerState
liftGhc :: Ghc a -> Debugger a
data DebuggerFailedToLoad = DebuggerFailedToLoad
data UnsupportedHsDbgViewVersion = UnsupportedHsDbgViewVersion {
- supportedVersions :: [(Version, Version)]
- actualVersion :: Version
}
data NonFatalException = NonFatalException {
- userMessage :: String
- debugMessage :: String
}
expectRight :: Exception e => Either e a -> Debugger a
getAllLoadedModules :: GhcMonad m => m [ModuleNodeInfo]
getAllLoadedModulesWithPaths :: GhcMonad m => m [(AbsFilePath, ModuleNodeInfo)]
defaultDepth :: Int
seqTerm :: HscEnv -> Term -> IO Term
deepseqTerm :: HscEnv -> Term -> IO Term
logSDoc :: Severity -> SDoc -> Debugger ()

Documentation

newtype Debugger a Source #

A debugger action.

Constructors

Debugger
Fields unDebugger :: ReaderT DebuggerState Ghc a

Instances

Instances details

MonadCatch Debugger Source #
Instance details Defined in GHC.Debugger.Monad Methods catch :: (HasCallStack, Exception e) => Debugger a -> (e -> Debugger a) -> Debugger a # catchNoPropagate :: Exception e => Debugger a -> (ExceptionWithContext e -> Debugger a) -> Debugger a #
MonadMask Debugger Source #
Instance details Defined in GHC.Debugger.Monad Methods mask :: HasCallStack => ((forall a. Debugger a -> Debugger a) -> Debugger b) -> Debugger b # uninterruptibleMask :: HasCallStack => ((forall a. Debugger a -> Debugger a) -> Debugger b) -> Debugger b # generalBracket :: HasCallStack => Debugger a -> (a -> ExitCase b -> Debugger c) -> (a -> Debugger b) -> Debugger (b, c) #
MonadThrow Debugger Source #
Instance details Defined in GHC.Debugger.Monad Methods throwM :: (HasCallStack, Exception e) => e -> Debugger a # rethrowM :: Exception e => ExceptionWithContext e -> Debugger a #
HasDynFlags Debugger Source #
Instance details Defined in GHC.Debugger.Monad Methods getDynFlags :: Debugger DynFlags #
GhcMonad Debugger Source #
Instance details Defined in GHC.Debugger.Monad Methods getSession :: Debugger HscEnv # setSession :: HscEnv -> Debugger () #
HasLogger Debugger Source #
Instance details Defined in GHC.Debugger.Monad Methods getLogger :: Debugger Logger #
Applicative Debugger Source #
Instance details Defined in GHC.Debugger.Monad Methods pure :: a -> Debugger a # (<>) :: Debugger (a -> b) -> Debugger a -> Debugger b # liftA2 :: (a -> b -> c) -> Debugger a -> Debugger b -> Debugger c # (>) :: Debugger a -> Debugger b -> Debugger b # (<*) :: Debugger a -> Debugger b -> Debugger a #
Functor Debugger Source #
Instance details Defined in GHC.Debugger.Monad Methods fmap :: (a -> b) -> Debugger a -> Debugger b # (<$) :: a -> Debugger b -> Debugger a #
Monad Debugger Source #
Instance details Defined in GHC.Debugger.Monad Methods (>>=) :: Debugger a -> (a -> Debugger b) -> Debugger b # (>>) :: Debugger a -> Debugger b -> Debugger b # return :: a -> Debugger a #
MonadIO Debugger Source #
Instance details Defined in GHC.Debugger.Monad Methods liftIO :: IO a -> Debugger a #
MonadReader DebuggerState Debugger Source #
Instance details Defined in GHC.Debugger.Monad Methods ask :: Debugger DebuggerState # local :: (DebuggerState -> DebuggerState) -> Debugger a -> Debugger a # reader :: (DebuggerState -> a) -> Debugger a #

data BreakpointInfo Source #

Constructors

BreakpointInfo
Fields bpInfoStatus :: !BreakpointStatus bpInfoKind :: !BreakpointKind bpInfoAction :: !BreakpointAction

Instances

Instances details

Eq BreakpointInfo Source #
Instance details Defined in GHC.Debugger.Monad Methods (==) :: BreakpointInfo -> BreakpointInfo -> Bool # (/=) :: BreakpointInfo -> BreakpointInfo -> Bool #
Show BreakpointInfo Source #
Instance details Defined in GHC.Debugger.Monad Methods showsPrec :: Int -> BreakpointInfo -> ShowS # show :: BreakpointInfo -> String # showList :: [BreakpointInfo] -> ShowS #

data DebuggerState Source #

State required to run the debugger.

Keep track of active breakpoints to easily unset them all.

Constructors

DebuggerState

Fields

activeBreakpoints :: IORef (BreakpointMap BreakpointInfo)
Maps a InternalBreakpointId in Trie representation (map of Module to map of Int) to the BreakpointStatus it was activated with.
rtinstancesCache :: IORef RuntimeInstancesCache
RuntimeInstancesCache
threadMap :: IORef ThreadMap
ThreadMap for threads spawned by the debuggee
compCache :: IORef CompCache
Cache loaded and compiled expressions.
hsDbgViewUnitId :: Maybe UnitId
The unit-id of the companion haskell-debugger-view unit, used for user-defined and built-in custom debug visualisations of values (e.g. for Strings or IntMap).
If the user depends on haskell-debugger-view in its transitive closure, then we should use that exact unit which was solved by Cabal. The built-in instances and additional instances be available for the DebugView class found in that unit. We can find the exact unit of the module by looking for haskell-debugger-view in the module graph.
If the user does not depend on haskell-debugger-view in any way, then we create our own unit and try to load the haskell-debugger-view modules directly into it. As long as loading succeeds, the DebugView class from this custom unit can be used to find the built-in instances for types like String
If the user explicitly disabled custom views, use Nothing.
dbgLogger :: LogAction Debugger DebuggerLog
See Note [Debugger, debuggee, and DAP logs]

Instances

Instances details

MonadReader DebuggerState Debugger Source #
Instance details Defined in GHC.Debugger.Monad Methods ask :: Debugger DebuggerState # local :: (DebuggerState -> DebuggerState) -> Debugger a -> Debugger a # reader :: (DebuggerState -> a) -> Debugger a #

data BreakpointStatus Source #

Enabling/Disabling a breakpoint

Constructors

BreakpointDisabled	Breakpoint is disabled Note: this must be the first constructor s.t. `BreakpointDisabled < {BreakpointEnabled, BreakpointAfterCount}`
BreakpointEnabled	Breakpoint is enabled
BreakpointAfterCount Int	Breakpoint is disabled the first N times and enabled afterwards
BreakpointWhenCond String	Breakpoint is enabled when condition evaluates to true
BreakpointAfterCountCond Int String	Breakpoint is disabled the first N times the condition evaluates to true and enabled in the next time it is true

Instances

Instances details

Outputable BreakpointStatus Source #
Instance details Defined in GHC.Debugger.Monad Methods ppr :: BreakpointStatus -> SDoc #
Eq BreakpointStatus Source #
Instance details Defined in GHC.Debugger.Monad Methods (==) :: BreakpointStatus -> BreakpointStatus -> Bool # (/=) :: BreakpointStatus -> BreakpointStatus -> Bool #
Ord BreakpointStatus Source #
Instance details Defined in GHC.Debugger.Monad Methods compare :: BreakpointStatus -> BreakpointStatus -> Ordering # (<) :: BreakpointStatus -> BreakpointStatus -> Bool # (<=) :: BreakpointStatus -> BreakpointStatus -> Bool # (>) :: BreakpointStatus -> BreakpointStatus -> Bool # (>=) :: BreakpointStatus -> BreakpointStatus -> Bool # max :: BreakpointStatus -> BreakpointStatus -> BreakpointStatus # min :: BreakpointStatus -> BreakpointStatus -> BreakpointStatus #
Show BreakpointStatus Source #
Instance details Defined in GHC.Debugger.Monad Methods showsPrec :: Int -> BreakpointStatus -> ShowS # show :: BreakpointStatus -> String # showList :: [BreakpointStatus] -> ShowS #

data BreakpointAction Source #

What to do when a breakpoint is enabled

Constructors

BreakpointStop	Evaluation is stopped, typical behaviour
BreakpointLogAndResume String	A log message is printed and then evaluation resumes. The `String` is an expression that takes care of interpolation and printing the log message.

Instances

Instances details

Outputable BreakpointAction Source #
Instance details Defined in GHC.Debugger.Monad Methods ppr :: BreakpointAction -> SDoc #
Eq BreakpointAction Source #
Instance details Defined in GHC.Debugger.Monad Methods (==) :: BreakpointAction -> BreakpointAction -> Bool # (/=) :: BreakpointAction -> BreakpointAction -> Bool #
Ord BreakpointAction Source #
Instance details Defined in GHC.Debugger.Monad Methods compare :: BreakpointAction -> BreakpointAction -> Ordering # (<) :: BreakpointAction -> BreakpointAction -> Bool # (<=) :: BreakpointAction -> BreakpointAction -> Bool # (>) :: BreakpointAction -> BreakpointAction -> Bool # (>=) :: BreakpointAction -> BreakpointAction -> Bool # max :: BreakpointAction -> BreakpointAction -> BreakpointAction # min :: BreakpointAction -> BreakpointAction -> BreakpointAction #
Show BreakpointAction Source #
Instance details Defined in GHC.Debugger.Monad Methods showsPrec :: Int -> BreakpointAction -> ShowS # show :: BreakpointAction -> String # showList :: [BreakpointAction] -> ShowS #

data RunDebuggerSettings Source #

Additional settings configuring the debugger

Constructors

RunDebuggerSettings
Fields supportsANSIStyling :: Bool supportsANSIHyperlinks :: Bool interpreterSettings :: InterpreterSettings

runDebugger :: LogAction IO DebuggerLog -> DebugRunner Ghc a -> RunDebuggerSettings -> Debugger a -> IO a Source #

Run a Debugger action on a session constructed by a DebugRunner

INVARIANT: The initUniqSupply has already been initialized.

Users of hdb-as-a-library will have to call initUniqSupply at their leisure, special care needed if they supply any loaded units/modules to us via the DebugRunner, as those will contain Uniques.

See Note [UniqueSupply is process global].

type DebugSession (m :: Type -> Type) a Source #

Arguments

= FilePath	project root dir
-> [String]	extra ghc args
-> m ()	action to load debugee home units
-> Ghc a

type DebugRunner (m :: Type -> Type) a = DebugSession m a -> IO a Source #

data ProjectDebugSpec Source #

Constructors

ProjectDebugSpec

Fields

rootDir :: FilePath
Project root directory
componentDir :: FilePath
Root dir of the loaded ComponentOptions. Important for multi-package cabal projects, as packages are not in the root of the cradle, but in some sub-directory.
libdir :: FilePath
The libdir (given with -B as an arg)
units :: [String]
The list of units included in the invocation
ghcInvocation :: [String]
The full ghc invocation (as constructed by hie-bios flags)
absEntryFile :: FilePath
Path to the main function
extraGhcArgs :: [String]

withProjectDebugSession :: GhcMonad m => ProjectDebugSpec -> DebugRunner m a Source #

Construct a session from paths and flags inferred from the debugee's project.

runDebuggerAction Source #

Arguments

:: LogAction IO DebuggerLog
-> FilePath	rootDir
-> [String]	extraGhcArgs
-> RunDebuggerSettings
-> Ghc ()	load home units action
-> Debugger a
-> Ghc a

preservingThreadLabel :: HasCallStack => Ghc a -> Ghc a Source #

loadInternal :: LogAction IO DebuggerLog -> Ways -> Ghc () Source #

Throws exception when module fails to load.

data FailedToLoadFFIInspectModule Source #

Constructors

FailedToLoadFFIInspectModule

Instances

Instances details

Exception FailedToLoadFFIInspectModule Source #
Instance details Defined in GHC.Debugger.Monad Methods toException :: FailedToLoadFFIInspectModule -> SomeException # fromException :: SomeException -> Maybe FailedToLoadFFIInspectModule # displayException :: FailedToLoadFFIInspectModule -> String # backtraceDesired :: FailedToLoadFFIInspectModule -> Bool #
Show FailedToLoadFFIInspectModule Source #
Instance details Defined in GHC.Debugger.Monad Methods showsPrec :: Int -> FailedToLoadFFIInspectModule -> ShowS # show :: FailedToLoadFFIInspectModule -> String # showList :: [FailedToLoadFFIInspectModule] -> ShowS #

loadFFIInspect :: LogAction IO DebuggerLog -> Ways -> Ghc () Source #

Throws exception when module fails to load. Needed for GHC.Debugger.Runtime.Interpreter.Legacy

findOrLoadHaskellDebuggerView :: LogAction IO DebuggerLog -> Ways -> Ghc (UnitId, [ModuleName]) Source #

cleanupInterp :: Ghc () Source #

See Note [Shutting down the external interpreter]

annotateDebuggerStackString :: String -> Debugger a -> Debugger a Source #

parseDynamicFlagsWithRootDir :: MonadIO m => FilePath -> Logger -> DynFlags -> [Located String] -> m (DynFlags, [Located String], Messages DriverMessage) Source #

Variant of GHC's parseDynamicFlags which interprets paths relative to first arg.

doDownsweep Source #

Arguments

:: GhcMonad m
=> Maybe ModuleGraph	Re-use existing module graph which was already summarised
-> m ModuleGraph	Module graph constructed from current set targets

Run downsweep on the currently set targets (see hsc_targets)

doLoad :: GhcMonad m => Maybe ModIfaceCache -> LoadHowMuch -> ModuleGraph -> m SuccessFlag Source #

loadInMemoryModules :: LogAction IO DebuggerLog -> UnitId -> [(ModuleName, StringBuffer)] -> Ghc [SuccessFlag] Source #

Finding Debugger View

getHsDebuggerViewUid :: Debugger (Maybe UnitId) Source #

Fetch the haskell-debugger-view unit-id from the environment. Nothing means custom debugger views are disabled.

findHsDebuggerViewUnitId :: Ghc (Maybe UnitId) Source #

Try to find the haskell-debugger-view unit-id in the transitive closure, or, otherwise, return the a custom unit for which we'll load the haskell-debugger-view modules in it (essentially preparing an in-memory version of the library to find the built-in instances in).

See also comment on the hsDbgViewUnitId field of DebuggerState

initialDebuggerState :: LogAction Debugger DebuggerLog -> Maybe UnitId -> Ghc DebuggerState Source #

Initialize a DebuggerState

liftGhc :: Ghc a -> Debugger a Source #

Lift a Ghc action into a Debugger one.

data DebuggerFailedToLoad Source #

Constructors

DebuggerFailedToLoad

Instances

Instances details

Exception DebuggerFailedToLoad Source #
Instance details Defined in GHC.Debugger.Monad Methods toException :: DebuggerFailedToLoad -> SomeException # fromException :: SomeException -> Maybe DebuggerFailedToLoad # displayException :: DebuggerFailedToLoad -> String # backtraceDesired :: DebuggerFailedToLoad -> Bool #
Show DebuggerFailedToLoad Source #
Instance details Defined in GHC.Debugger.Monad Methods showsPrec :: Int -> DebuggerFailedToLoad -> ShowS # show :: DebuggerFailedToLoad -> String # showList :: [DebuggerFailedToLoad] -> ShowS #

data UnsupportedHsDbgViewVersion Source #

Constructors

UnsupportedHsDbgViewVersion
Fields supportedVersions :: [(Version, Version)] actualVersion :: Version

Instances

Instances details

Exception UnsupportedHsDbgViewVersion Source #
Instance details Defined in GHC.Debugger.Monad Methods toException :: UnsupportedHsDbgViewVersion -> SomeException # fromException :: SomeException -> Maybe UnsupportedHsDbgViewVersion # displayException :: UnsupportedHsDbgViewVersion -> String # backtraceDesired :: UnsupportedHsDbgViewVersion -> Bool #
Show UnsupportedHsDbgViewVersion Source #
Instance details Defined in GHC.Debugger.Monad Methods showsPrec :: Int -> UnsupportedHsDbgViewVersion -> ShowS # show :: UnsupportedHsDbgViewVersion -> String # showList :: [UnsupportedHsDbgViewVersion] -> ShowS #

data NonFatalException Source #

Constructors

NonFatalException
Fields userMessage :: String debugMessage :: String

Instances

Instances details

Exception NonFatalException Source #
Instance details Defined in GHC.Debugger.Monad Methods toException :: NonFatalException -> SomeException # fromException :: SomeException -> Maybe NonFatalException # displayException :: NonFatalException -> String # backtraceDesired :: NonFatalException -> Bool #
Show NonFatalException Source #
Instance details Defined in GHC.Debugger.Monad Methods showsPrec :: Int -> NonFatalException -> ShowS # show :: NonFatalException -> String # showList :: [NonFatalException] -> ShowS #

expectRight :: Exception e => Either e a -> Debugger a Source #

Modules

getAllLoadedModules :: GhcMonad m => m [ModuleNodeInfo] Source #

List all loaded modules ModSummarys

getAllLoadedModulesWithPaths :: GhcMonad m => m [(AbsFilePath, ModuleNodeInfo)] Source #

Forcing laziness

defaultDepth :: Int Source #

The depth determines how much of the runtime structure is traversed. obtainTerm and friends handle fetching arbitrarily nested data structures so we only depth enough to get to the next level of subterms.

seqTerm :: HscEnv -> Term -> IO Term Source #

Evaluate a suspended Term to WHNF.

Used in getVariables to reply to a variable introspection request.

deepseqTerm :: HscEnv -> Term -> IO Term Source #

Evaluate a Term to NF

logSDoc :: Severity -> SDoc -> Debugger () Source #