GHC.Utils.Panic

ghc-9.10.0.20240426: The GHC API

Safe Haskell | None
Language | GHC2021

GHC.Utils.Panic

Contents

- GHC exception type
- Command error throwing patterns
  - Assertions
- Call stacks
- Exception utilities

Description

Defines basic functions for printing error messages.

It's hard to put these functions anywhere else without causing some unnecessary loops in the module dependency graph.

Synopsis

- data GhcException
  - = Signal Int
  - | UsageError String
  - | CmdLineError String
  - | Panic String
  - | PprPanic String SDoc
  - | Sorry String
  - | PprSorry String SDoc
  - | InstallationError String
  - | ProgramError String
  - | PprProgramError String SDoc
- showGhcException :: SDocContext -> GhcException -> ShowS
- showGhcExceptionUnsafe :: GhcException -> ShowS
- throwGhcException :: GhcException -> a
- throwGhcExceptionIO :: GhcException -> IO a
- handleGhcException :: ExceptionMonad m => (GhcException -> m a) -> m a -> m a
- pprPanic :: HasCallStack => String -> SDoc -> a
- panicDoc :: String -> SDoc -> a
- sorryDoc :: String -> SDoc -> a
- pgmErrorDoc :: String -> SDoc -> a
- assertPprPanic :: HasCallStack => SDoc -> a
- assertPpr :: HasCallStack => Bool -> SDoc -> a -> a
- assertPprMaybe :: HasCallStack => Maybe SDoc -> a -> a
- assertPprM :: (HasCallStack, Monad m) => m Bool -> SDoc -> m ()
- massertPpr :: (HasCallStack, Applicative m) => Bool -> SDoc -> m ()
- callStackDoc :: HasCallStack => SDoc
- prettyCallStackDoc :: CallStack -> SDoc
- class (Typeable e, Show e) => Exception e where
  - toException :: e -> SomeException
  - fromException :: SomeException -> Maybe e
  - displayException :: e -> String
  - backtraceDesired :: e -> Bool
- showException :: Exception e => e -> String
- safeShowException :: Exception e => e -> IO String
- try :: Exception e => IO a -> IO (Either e a)
- tryMost :: IO a -> IO (Either SomeException a)
- throwTo :: Exception e => ThreadId -> e -> IO ()
- withSignalHandlers :: ExceptionMonad m => m a -> m a
- module GHC.Utils.Panic.Plain

# GHC exception type

data GhcException Source #

GHC's own exception type error messages all take the form:

         <location>: <error>

If the location is on the command line, or in GHC itself, then <location>="ghc". All of the error types below correspond to a <location> of "ghc", except for ProgramError (where the string is assumed to contain a location already, so we don't print one).

Constructors

Signal Int | Some other fatal signal (SIGHUP,SIGTERM)
UsageError String | Prints the short usage msg after the error
CmdLineError String | A problem with the command line arguments, but don't print usage.
Panic String | The `impossible` happened.
PprPanic String SDoc |
Sorry String | The user tickled something that's known not to work yet, but we're not counting it as a bug.
PprSorry String SDoc |
InstallationError String | An installation problem.
ProgramError String | An error in the user's code, probably.
PprProgramError String SDoc |

#### Instances

Instances details

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

showGhcException :: SDocContext -> GhcException -> ShowS Source #

Append a description of the given exception to this string.

showGhcExceptionUnsafe :: GhcException -> ShowS Source #

Append a description of the given exception to this string.

Note that this uses `defaultSDocContext`, which doesn't use the options set by the user via DynFlags.

throwGhcException :: GhcException -> a Source #

throwGhcExceptionIO :: GhcException -> IO a Source #

handleGhcException :: ExceptionMonad m => (GhcException -> m a) -> m a -> m a Source #

# Command error throwing patterns

pprPanic :: HasCallStack => String -> SDoc -> a Source #

Throw an exception saying "bug in GHC" with a callstack

panicDoc :: String -> SDoc -> a Source #

Throw an exception saying "bug in GHC"

sorryDoc :: String -> SDoc -> a Source #

Throw an exception saying "this isn't finished yet"

pgmErrorDoc :: String -> SDoc -> a Source #

Throw an exception saying "bug in pgm being compiled" (used for unusual program errors)

## Assertions

assertPprPanic :: HasCallStack => SDoc -> a Source #

Panic with an assertion failure, recording the given file and line number. Should typically be accessed with the ASSERT family of macros

assertPpr :: HasCallStack => Bool -> SDoc -> a -> a Source #

assertPprMaybe :: HasCallStack => Maybe SDoc -> a -> a Source #

assertPprM :: (HasCallStack, Monad m) => m Bool -> SDoc -> m () Source #

massertPpr :: (HasCallStack, Applicative m) => Bool -> SDoc -> m () Source #

# Call stacks

callStackDoc :: HasCallStack => SDoc Source #

prettyCallStackDoc :: CallStack -> SDoc Source #

# Exception utilities

class (Typeable e, Show e) => Exception e where #

Minimal complete definition

Nothing

Methods

toException :: e -> SomeException #

fromException :: SomeException -> Maybe e #

displayException :: e -> String #

backtraceDesired :: e -> Bool #

#### Instances

Instances details

Exception Timeout | Since: base-4.7.0.0
Instance details Defined in System.Timeout Methods toException :: Timeout -> SomeException # fromException :: SomeException -> Maybe Timeout # displayException :: Timeout -> String # backtraceDesired :: Timeout -> Bool #
Exception SizeOverflowException |
Instance details Defined in Data.ByteString.Internal.Type Methods toException :: SizeOverflowException -> SomeException # fromException :: SomeException -> Maybe SizeOverflowException # displayException :: SizeOverflowException -> String # backtraceDesired :: SizeOverflowException -> Bool #
Exception GhcApiError Source # |
Instance details Defined in GHC Methods toException :: GhcApiError -> SomeException # fromException :: SomeException -> Maybe GhcApiError # displayException :: GhcApiError -> String # backtraceDesired :: GhcApiError -> Bool #
Exception IOEnvFailure Source # |
Instance details Defined in GHC.Data.IOEnv Methods toException :: IOEnvFailure -> SomeException # fromException :: SomeException -> Maybe IOEnvFailure # displayException :: IOEnvFailure -> String # backtraceDesired :: IOEnvFailure -> Bool #
Exception SourceError Source # |
Instance details Defined in GHC.Types.SourceError Methods toException :: SourceError -> SomeException # fromException :: SomeException -> Maybe SourceError # displayException :: SourceError -> String # backtraceDesired :: SourceError -> Bool #
Exception GhcException Source # |
Instance details Defined in GHC.Utils.Panic Methods toException :: GhcException -> SomeException # fromException :: SomeException -> Maybe GhcException # displayException :: GhcException -> String # backtraceDesired :: GhcException -> Bool #
Exception PlainGhcException Source # |
Instance details Defined in GHC.Utils.Panic.Plain Methods toException :: PlainGhcException -> SomeException # fromException :: SomeException -> Maybe PlainGhcException # displayException :: PlainGhcException -> String # backtraceDesired :: PlainGhcException -> Bool #
Exception Void |
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: Void -> SomeException # fromException :: SomeException -> Maybe Void # displayException :: Void -> String # backtraceDesired :: Void -> Bool #
Exception NestedAtomically |
Instance details Defined in GHC.Internal.Control.Exception.Base Methods toException :: NestedAtomically -> SomeException # fromException :: SomeException -> Maybe NestedAtomically # displayException :: NestedAtomically -> String # backtraceDesired :: NestedAtomically -> Bool #
Exception NoMatchingContinuationPrompt |
Instance details Defined in GHC.Internal.Control.Exception.Base Methods toException :: NoMatchingContinuationPrompt -> SomeException # fromException :: SomeException -> Maybe NoMatchingContinuationPrompt # displayException :: NoMatchingContinuationPrompt -> String # backtraceDesired :: NoMatchingContinuationPrompt -> Bool #
Exception NoMethodError |
Instance details Defined in GHC.Internal.Control.Exception.Base Methods toException :: NoMethodError -> SomeException # fromException :: SomeException -> Maybe NoMethodError # displayException :: NoMethodError -> String # backtraceDesired :: NoMethodError -> Bool #
Exception NonTermination |
Instance details Defined in GHC.Internal.Control.Exception.Base Methods toException :: NonTermination -> SomeException # fromException :: SomeException -> Maybe NonTermination # displayException :: NonTermination -> String # backtraceDesired :: NonTermination -> Bool #
Exception PatternMatchFail |
Instance details Defined in GHC.Internal.Control.Exception.Base Methods toException :: PatternMatchFail -> SomeException # fromException :: SomeException -> Maybe PatternMatchFail # displayException :: PatternMatchFail -> String # backtraceDesired :: PatternMatchFail -> Bool #
Exception RecConError |
Instance details Defined in GHC.Internal.Control.Exception.Base Methods toException :: RecConError -> SomeException # fromException :: SomeException -> Maybe RecConError # displayException :: RecConError -> String # backtraceDesired :: RecConError -> Bool #
Exception RecSelError |
Instance details Defined in GHC.Internal.Control.Exception.Base Methods toException :: RecSelError -> SomeException # fromException :: SomeException -> Maybe RecSelError # displayException :: RecSelError -> String # backtraceDesired :: RecSelError -> Bool #
Exception RecUpdError |
Instance details Defined in GHC.Internal.Control.Exception.Base Methods toException :: RecUpdError -> SomeException # fromException :: SomeException -> Maybe RecUpdError # displayException :: RecUpdError -> String # backtraceDesired :: RecUpdError -> Bool #
Exception TypeError |
Instance details Defined in GHC.Internal.Control.Exception.Base Methods toException :: TypeError -> SomeException # fromException :: SomeException -> Maybe TypeError # displayException :: TypeError -> String # backtraceDesired :: TypeError -> Bool #
Exception Dynamic |
Instance details Defined in GHC.Internal.Data.Dynamic Methods toException :: Dynamic -> SomeException # fromException :: SomeException -> Maybe Dynamic # displayException :: Dynamic -> String # backtraceDesired :: Dynamic -> Bool #
Exception ErrorCall |
Instance details Defined in GHC.Internal.Exception Methods toException :: ErrorCall -> SomeException # fromException :: SomeException -> Maybe ErrorCall # displayException :: ErrorCall -> String # backtraceDesired :: ErrorCall -> Bool #
Exception ArithException |
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: ArithException -> SomeException # fromException :: SomeException -> Maybe ArithException # displayException :: ArithException -> String # backtraceDesired :: ArithException -> Bool #
Exception SomeException |
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: SomeException -> SomeException # fromException :: SomeException -> Maybe SomeException # displayException :: SomeException -> String # backtraceDesired :: SomeException -> Bool #
Exception AllocationLimitExceeded |
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: AllocationLimitExceeded -> SomeException # fromException :: SomeException -> Maybe AllocationLimitExceeded # displayException :: AllocationLimitExceeded -> String # backtraceDesired :: AllocationLimitExceeded -> Bool #
Exception ArrayException |
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: ArrayException -> SomeException # fromException :: SomeException -> Maybe ArrayException # displayException :: ArrayException -> String # backtraceDesired :: ArrayException -> Bool #
Exception AssertionFailed |
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: AssertionFailed -> SomeException # fromException :: SomeException -> Maybe AssertionFailed # displayException :: AssertionFailed -> String # backtraceDesired :: AssertionFailed -> Bool #
Exception AsyncException |
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: AsyncException -> SomeException # fromException :: SomeException -> Maybe AsyncException # displayException :: AsyncException -> String # backtraceDesired :: AsyncException -> Bool #
Exception BlockedIndefinitelyOnMVar |
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: BlockedIndefinitelyOnMVar -> SomeException # fromException :: SomeException -> Maybe BlockedIndefinitelyOnMVar # displayException :: BlockedIndefinitelyOnMVar -> String # backtraceDesired :: BlockedIndefinitelyOnMVar -> Bool #
Exception BlockedIndefinitelyOnSTM |
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: BlockedIndefinitelyOnSTM -> SomeException # fromException :: SomeException -> Maybe BlockedIndefinitelyOnSTM # displayException :: BlockedIndefinitelyOnSTM -> String # backtraceDesired :: BlockedIndefinitelyOnSTM -> Bool #
Exception CompactionFailed |
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: CompactionFailed -> SomeException # fromException :: SomeException -> Maybe CompactionFailed # displayException :: CompactionFailed -> String # backtraceDesired :: CompactionFailed -> Bool #
Exception Deadlock |
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: Deadlock -> SomeException # fromException :: SomeException -> Maybe Deadlock # displayException :: Deadlock -> String # backtraceDesired :: Deadlock -> Bool #
Exception ExitCode |
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: ExitCode -> SomeException # fromException :: SomeException -> Maybe ExitCode # displayException :: ExitCode -> String # backtraceDesired :: ExitCode -> Bool #
Exception FixIOException |
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: FixIOException -> SomeException # fromException :: SomeException -> Maybe FixIOException # displayException :: FixIOException -> String # backtraceDesired :: FixIOException -> Bool #
Exception IOException |
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: IOException -> SomeException # fromException :: SomeException -> Maybe IOException # displayException :: IOException -> String # backtraceDesired :: IOException -> Bool #
Exception SomeAsyncException |
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: SomeAsyncException -> SomeException # fromException :: SomeException -> Maybe SomeAsyncException # displayException :: SomeAsyncException -> String # backtraceDesired :: SomeAsyncException -> Bool #
Exception GHCiQException |
Instance details Defined in GHCi.TH Methods toException :: GHCiQException -> SomeException # fromException :: SomeException -> Maybe GHCiQException # displayException :: GHCiQException -> String # backtraceDesired :: GHCiQException -> Bool #
Exception a => Exception (ExceptionWithContext a) |
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: ExceptionWithContext a -> SomeException # fromException :: SomeException -> Maybe (ExceptionWithContext a) # displayException :: ExceptionWithContext a -> String # backtraceDesired :: ExceptionWithContext a -> Bool #
Exception e => Exception (NoBacktrace e) |
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: NoBacktrace e -> SomeException # fromException :: SomeException -> Maybe (NoBacktrace e) # displayException :: NoBacktrace e -> String # backtraceDesired :: NoBacktrace e -> Bool #

showException :: Exception e => e -> String Source #

Show an exception as a string.

safeShowException :: Exception e => e -> IO String Source #

Show an exception which can possibly throw other exceptions. Used when displaying exception thrown within TH code.

try :: Exception e => IO a -> IO (Either e a) #

tryMost :: IO a -> IO (Either SomeException a) Source #

Like try, but pass through UserInterrupt and Panic exceptions. Used when we want soft failures when reading interface files, for example. TODO: I'm not entirely sure if this is catching what we really want to catch

throwTo :: Exception e => ThreadId -> e -> IO () #

withSignalHandlers :: ExceptionMonad m => m a -> m a Source #

Temporarily install standard signal handlers for catching ^C, which just throw an exception in the current thread.

module GHC.Utils.Panic.Plain