ghc-8.2.2: The GHC API

Safe Haskell | None
Language | Haskell2010

GHCi

Contents

- High-level interface to the interpreter
- The object-code linker
- Lower-level API using messages

Description

Interacting with the interpreter, whether it is running on an external process or in the current process.

Synopsis

- evalStmt :: HscEnv -> Bool -> EvalExpr ForeignHValue -> IO (EvalStatus_ [ForeignHValue] [HValueRef])
- data EvalStatus_ a b :: * -> * -> *
  - = EvalComplete Word64 (EvalResult a)
  - | EvalBreak Bool HValueRef Int Int (RemoteRef (ResumeContext b)) (RemotePtr CostCentreStack)
- type EvalStatus a = EvalStatus_ a a
- data EvalResult a :: * -> *
  - = EvalException SerializableException
  - | EvalSuccess a
- data EvalExpr a :: * -> *
  - = EvalThis a
  - | EvalApp (EvalExpr a) (EvalExpr a)
- resumeStmt :: HscEnv -> Bool -> ForeignRef (ResumeContext [HValueRef]) -> IO (EvalStatus_ [ForeignHValue] [HValueRef])
- abandonStmt :: HscEnv -> ForeignRef (ResumeContext [HValueRef]) -> IO ()
- evalIO :: HscEnv -> ForeignHValue -> IO ()
- evalString :: HscEnv -> ForeignHValue -> IO String
- evalStringToIOString :: HscEnv -> ForeignHValue -> String -> IO String
- mallocData :: HscEnv -> ByteString -> IO (RemotePtr ())
- createBCOs :: HscEnv -> [ResolvedBCO] -> IO [HValueRef]
- addSptEntry :: HscEnv -> Fingerprint -> ForeignHValue -> IO ()
- mkCostCentres :: HscEnv -> String -> [(String, String)] -> IO [RemotePtr CostCentre]
- costCentreStackInfo :: HscEnv -> RemotePtr CostCentreStack -> IO [String]
- newBreakArray :: HscEnv -> Int -> IO (ForeignRef BreakArray)
- enableBreakpoint :: HscEnv -> ForeignRef BreakArray -> Int -> Bool -> IO ()
- breakpointStatus :: HscEnv -> ForeignRef BreakArray -> Int -> IO Bool
- getBreakpointVar :: HscEnv -> ForeignHValue -> Int -> IO (Maybe ForeignHValue)
- initObjLinker :: HscEnv -> IO ()
- lookupSymbol :: HscEnv -> FastString -> IO (Maybe (Ptr ()))
- lookupClosure :: HscEnv -> String -> IO (Maybe HValueRef)
- loadDLL :: HscEnv -> String -> IO (Maybe String)
- loadArchive :: HscEnv -> String -> IO ()
- loadObj :: HscEnv -> String -> IO ()
- unloadObj :: HscEnv -> String -> IO ()
- addLibrarySearchPath :: HscEnv -> String -> IO (Ptr ())
- removeLibrarySearchPath :: HscEnv -> Ptr () -> IO Bool
- resolveObjs :: HscEnv -> IO SuccessFlag
- findSystemLibrary :: HscEnv -> String -> IO (Maybe String)
- iservCmd :: Binary a => HscEnv -> Message a -> IO a
- data Message a :: * -> * where
  - Shutdown :: Message ()
  - InitLinker :: Message ()
  - LookupSymbol :: Message (Maybe (RemotePtr ()))
  - LookupClosure :: Message (Maybe HValueRef)
  - LoadDLL :: Message (Maybe String)
  - LoadArchive :: Message ()
  - LoadObj :: Message ()
  - UnloadObj :: Message ()
  - AddLibrarySearchPath :: Message (RemotePtr ())
  - RemoveLibrarySearchPath :: Message Bool
  - ResolveObjs :: Message Bool
  - FindSystemLibrary :: Message (Maybe String)
  - CreateBCOs :: Message [HValueRef]
  - FreeHValueRefs :: Message ()
  - AddSptEntry :: Message ()
  - MallocData :: Message (RemotePtr ())
  - MallocStrings :: Message [RemotePtr ()]
  - PrepFFI :: Message (RemotePtr C_ffi_cif)
  - FreeFFI :: Message ()
  - MkConInfoTable :: Message (RemotePtr StgInfoTable)
  - EvalStmt :: Message (EvalStatus_ [HValueRef] [HValueRef])
  - ResumeStmt :: Message (EvalStatus_ [HValueRef] [HValueRef])
  - AbandonStmt :: Message ()
  - EvalString :: Message (EvalResult String)
  - EvalStringToString :: Message (EvalResult String)
  - EvalIO :: Message (EvalResult ())
  - MkCostCentres :: Message [RemotePtr CostCentre]
  - CostCentreStackInfo :: Message [String]
  - NewBreakArray :: Message (RemoteRef BreakArray)
  - EnableBreakpoint :: Message ()
  - BreakpointStatus :: Message Bool
  - GetBreakpointVar :: Message (Maybe HValueRef)
  - StartTH :: Message (RemoteRef (IORef QState))
  - RunTH :: Message (QResult ByteString)
  - RunModFinalizers :: Message (QResult ())
- withIServ :: (MonadIO m, ExceptionMonad m) => HscEnv -> (IServ -> m a) -> m a
- stopIServ :: HscEnv -> IO ()
- iservCall :: Binary a => IServ -> Message a -> IO a
- readIServ :: IServ -> Get a -> IO a
- writeIServ :: IServ -> Put -> IO ()
- purgeLookupSymbolCache :: HscEnv -> IO ()
- freeHValueRefs :: HscEnv -> [HValueRef] -> IO ()
- mkFinalizedHValue :: HscEnv -> RemoteRef a -> IO (ForeignRef a)
- wormhole :: DynFlags -> ForeignRef a -> IO a
- wormholeRef :: DynFlags -> RemoteRef a -> IO a
- mkEvalOpts :: DynFlags -> Bool -> EvalOpts
- fromEvalResult :: EvalResult a -> IO a

# High-level interface to the interpreter

evalStmt :: HscEnv -> Bool -> EvalExpr ForeignHValue -> IO (EvalStatus_ [ForeignHValue] [HValueRef]) #

Execute an action of type `IO [a]`, returning `ForeignHValue`s for each of the results.

data EvalStatus_ a b :: * -> * -> * Source #

Constructors

EvalComplete Word64 (EvalResult a) |
EvalBreak Bool HValueRef Int Int (RemoteRef (ResumeContext b)) (RemotePtr CostCentreStack) |

Instances

Show a => Show (EvalStatus_ a b) |
Methods showsPrec :: Int -> EvalStatus_ a b -> ShowS Source # show :: EvalStatus_ a b -> String Source # showList :: [EvalStatus_ a b] -> ShowS Source #
Generic (EvalStatus_ a b) |
Associated Types type Rep (EvalStatus_ a b) :: * -> * Source # Methods from :: EvalStatus_ a b -> Rep (EvalStatus_ a b) x Source # to :: Rep (EvalStatus_ a b) x -> EvalStatus_ a b Source #
Binary a => Binary (EvalStatus_ a b) |
Methods put :: EvalStatus_ a b -> Put Source # get :: Get (EvalStatus_ a b) Source # putList :: [EvalStatus_ a b] -> Put Source #
type Rep (EvalStatus_ a b) |

type Rep (EvalStatus_ a b) = D1 * (MetaData "EvalStatus_" "GHCi.Message" "ghci-8.2.2" False) ((:+:) * (C1 * (MetaCons "EvalComplete" PrefixI False) ((:*:) * (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * Word64)) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * (EvalResult a))))) (C1 * (MetaCons "EvalBreak" PrefixI False) ((:*:) * ((:*:) * (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * Bool)) ((:*:) * (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * HValueRef)) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * Int)))) ((:*:) * (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * Int)) ((:*:) * (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * (RemoteRef (ResumeContext b)))) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * (RemotePtr CostCentreStack))))))))

type EvalStatus a = EvalStatus_ a a Source #

data EvalResult a :: * -> * Source #

Constructors

EvalException SerializableException |
EvalSuccess a |

Instances

Show a => Show (EvalResult a) |
Methods showsPrec :: Int -> EvalResult a -> ShowS Source # show :: EvalResult a -> String Source # showList :: [EvalResult a] -> ShowS Source #
Generic (EvalResult a) |
Associated Types type Rep (EvalResult a) :: * -> * Source # Methods from :: EvalResult a -> Rep (EvalResult a) x Source # to :: Rep (EvalResult a) x -> EvalResult a Source #
Binary a => Binary (EvalResult a) |
Methods put :: EvalResult a -> Put Source # get :: Get (EvalResult a) Source # putList :: [EvalResult a] -> Put Source #
type Rep (EvalResult a) |

type Rep (EvalResult a) = D1 * (MetaData "EvalResult" "GHCi.Message" "ghci-8.2.2" False) ((:+:) * (C1 * (MetaCons "EvalException" PrefixI False) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * SerializableException))) (C1 * (MetaCons "EvalSuccess" PrefixI False) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * a))))

data EvalExpr a :: * -> * Source #

We can pass simple expressions to EvalStmt, consisting of values and application. This allows us to wrap the statement to be executed in another function, which is used by GHCi to implement :set args and :set prog. It might be worthwhile to extend this little language in the future.

Constructors

EvalThis a |
EvalApp (EvalExpr a) (EvalExpr a) |

Instances

Show a => Show (EvalExpr a) |
Methods showsPrec :: Int -> EvalExpr a -> ShowS Source # show :: EvalExpr a -> String Source # showList :: [EvalExpr a] -> ShowS Source #
Generic (EvalExpr a) |
Associated Types type Rep (EvalExpr a) :: * -> * Source # Methods from :: EvalExpr a -> Rep (EvalExpr a) x Source # to :: Rep (EvalExpr a) x -> EvalExpr a Source #
Binary a => Binary (EvalExpr a) |
Methods put :: EvalExpr a -> Put Source # get :: Get (EvalExpr a) Source # putList :: [EvalExpr a] -> Put Source #
type Rep (EvalExpr a) |

type Rep (EvalExpr a) = D1 * (MetaData "EvalExpr" "GHCi.Message" "ghci-8.2.2" False) ((:+:) * (C1 * (MetaCons "EvalThis" PrefixI False) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * a))) (C1 * (MetaCons "EvalApp" PrefixI False) ((:*:) * (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * (EvalExpr a))) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * (EvalExpr a))))))

resumeStmt :: HscEnv -> Bool -> ForeignRef (ResumeContext [HValueRef]) -> IO (EvalStatus_ [ForeignHValue] [HValueRef]) #

abandonStmt :: HscEnv -> ForeignRef (ResumeContext [HValueRef]) -> IO () #

evalIO :: HscEnv -> ForeignHValue -> IO () #

Execute an action of type `IO ()`

evalString :: HscEnv -> ForeignHValue -> IO String #

Execute an action of type `IO String`

evalStringToIOString :: HscEnv -> ForeignHValue -> String -> IO String #

Execute an action of type `String -> IO String`

mallocData :: HscEnv -> ByteString -> IO (RemotePtr ()) #

Allocate and store the given bytes in memory, returning a pointer to the memory in the remote process.

createBCOs :: HscEnv -> [ResolvedBCO] -> IO [HValueRef] #

Create a set of BCOs that may be mutually recursive.

addSptEntry :: HscEnv -> Fingerprint -> ForeignHValue -> IO () #

mkCostCentres :: HscEnv -> String -> [(String, String)] -> IO [RemotePtr CostCentre] #

costCentreStackInfo :: HscEnv -> RemotePtr CostCentreStack -> IO [String] #

newBreakArray :: HscEnv -> Int -> IO (ForeignRef BreakArray) #

enableBreakpoint :: HscEnv -> ForeignRef BreakArray -> Int -> Bool -> IO () #

breakpointStatus :: HscEnv -> ForeignRef BreakArray -> Int -> IO Bool #

getBreakpointVar :: HscEnv -> ForeignHValue -> Int -> IO (Maybe ForeignHValue) #

# The object-code linker

initObjLinker :: HscEnv -> IO () #

lookupSymbol :: HscEnv -> FastString -> IO (Maybe (Ptr ())) #

lookupClosure :: HscEnv -> String -> IO (Maybe HValueRef) #

loadDLL :: HscEnv -> String -> IO (Maybe String) #

loadDLL loads a dynamic library using the OS's native linker (i.e. dlopen() on Unix, LoadLibrary() on Windows). It takes either an absolute pathname to the file, or a relative filename (e.g. "libfoo.so" or "foo.dll"). In the latter case, loadDLL searches the standard locations for the appropriate library.

Returns:

Nothing => success Just err_msg => failure

loadArchive :: HscEnv -> String -> IO () #

loadObj :: HscEnv -> String -> IO () #

unloadObj :: HscEnv -> String -> IO () #

addLibrarySearchPath :: HscEnv -> String -> IO (Ptr ()) #

removeLibrarySearchPath :: HscEnv -> Ptr () -> IO Bool #

resolveObjs :: HscEnv -> IO SuccessFlag #

findSystemLibrary :: HscEnv -> String -> IO (Maybe String) #

# Lower-level API using messages

iservCmd :: Binary a => HscEnv -> Message a -> IO a #

Run a command in the interpreter's context. With `-fexternal-interpreter`, the command is serialized and sent to an external iserv process, and the response is deserialized (hence the `Binary` constraint). With `-fno-external-interpreter` we execute the command directly here.

data Message a :: * -> * where Source #

A `Message a` is a message that returns a value of type `a`. These are requests sent from GHC to the server.

Constructors

Shutdown :: Message () | Exit the iserv process
InitLinker :: Message () |
LookupSymbol :: Message (Maybe (RemotePtr ())) |
LookupClosure :: Message (Maybe HValueRef) |
LoadDLL :: Message (Maybe String) |
LoadArchive :: Message () |
LoadObj :: Message () |
UnloadObj :: Message () |
AddLibrarySearchPath :: Message (RemotePtr ()) |
RemoveLibrarySearchPath :: Message Bool |
ResolveObjs :: Message Bool |
FindSystemLibrary :: Message (Maybe String) |
CreateBCOs :: Message [HValueRef] | Create a set of BCO objects, and return HValueRefs to them Note: Each ByteString contains a Binary-encoded [ResolvedBCO], not a ResolvedBCO. The list is to allow us to serialise the ResolvedBCOs in parallel. See `createBCOs` in compilerghciGHCi.hsc.
FreeHValueRefs :: Message () | Release `HValueRef`s
AddSptEntry :: Message () | Add entries to the Static Pointer Table
MallocData :: Message (RemotePtr ()) | Malloc some data and return a `RemotePtr` to it
MallocStrings :: Message [RemotePtr ()] |
PrepFFI :: Message (RemotePtr C_ffi_cif) | Calls `prepareForeignCall`
FreeFFI :: Message () | Free data previously created by `PrepFFI`
MkConInfoTable :: Message (RemotePtr StgInfoTable) | Create an info table for a constructor
EvalStmt :: Message (EvalStatus_ [HValueRef] [HValueRef]) | Evaluate a statement
ResumeStmt :: Message (EvalStatus_ [HValueRef] [HValueRef]) | Resume evaluation of a statement after a breakpoint
AbandonStmt :: Message () | Abandon evaluation of a statement after a breakpoint
EvalString :: Message (EvalResult String) | Evaluate something of type `IO String`
EvalStringToString :: Message (EvalResult String) | Evaluate something of type `String -> IO String`
EvalIO :: Message (EvalResult ()) | Evaluate something of type `IO ()`
MkCostCentres :: Message [RemotePtr CostCentre] | Create a set of CostCentres with the same module name
CostCentreStackInfo :: Message [String] | Show a `CostCentreStack` as a `[String]`
NewBreakArray :: Message (RemoteRef BreakArray) | Create a new array of breakpoint flags
EnableBreakpoint :: Message () | Enable a breakpoint
BreakpointStatus :: Message Bool | Query the status of a breakpoint (True = enabled)
GetBreakpointVar :: Message (Maybe HValueRef) | Get a reference to a free variable at a breakpoint
StartTH :: Message (RemoteRef (IORef QState)) | Start a new TH module, return a state token that should be
RunTH :: Message (QResult ByteString) | Evaluate a TH computation. Returns a ByteString, because we have to force the result before returning it to ensure there are no errors lurking in it. The TH types don't have NFData instances, and even if they did, we have to serialize the value anyway, so we might as well serialize it to force it.
RunModFinalizers :: Message (QResult ()) | Run the given mod finalizers.

Instances

Show (Message a) |
Methods showsPrec :: Int -> Message a -> ShowS Source # show :: Message a -> String Source # showList :: [Message a] -> ShowS Source #

withIServ :: (MonadIO m, ExceptionMonad m) => HscEnv -> (IServ -> m a) -> m a #

Grab a lock on the `IServ` and do something with it. Overloaded because this is used from TcM as well as IO.

stopIServ :: HscEnv -> IO () #

iservCall :: Binary a => IServ -> Message a -> IO a #

Send a `Message` and receive the response from the iserv process

readIServ :: IServ -> Get a -> IO a #

Read a value from the iserv process

writeIServ :: IServ -> Put -> IO () #

Send a value to the iserv process

purgeLookupSymbolCache :: HscEnv -> IO () #

freeHValueRefs :: HscEnv -> [HValueRef] -> IO () #

mkFinalizedHValue :: HscEnv -> RemoteRef a -> IO (ForeignRef a) #

Creates a `ForeignRef` that will automatically release the `RemoteRef` when it is no longer referenced.

wormhole :: DynFlags -> ForeignRef a -> IO a #

Convert a `ForeignRef` to the value it references directly. This only works when the interpreter is running in the same process as the compiler, so it fails when `-fexternal-interpreter` is on.

wormholeRef :: DynFlags -> RemoteRef a -> IO a #

Convert an `RemoteRef` to the value it references directly. This only works when the interpreter is running in the same process as the compiler, so it fails when `-fexternal-interpreter` is on.

mkEvalOpts :: DynFlags -> Bool -> EvalOpts #

fromEvalResult :: EvalResult a -> IO a #