GHCi

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

High-level interface to the interpreter

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

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

data EvalStatus_ a b

Constructors

EvalComplete Word64 (EvalResult a)

EvalBreak Bool HValueRef Int Int (RemoteRef (ResumeContext b)) (RemotePtr CostCentreStack)

Instances

Show a => Show (EvalStatus_ a b)

Defined in GHCi.Message

Methods

showsPrec :: Int -> EvalStatus_ a b -> ShowS

show :: EvalStatus_ a b -> String

showList :: [EvalStatus_ a b] -> ShowS

Generic (EvalStatus_ a b)

Defined in GHCi.Message

Associated Types

type Rep (EvalStatus_ a b) :: Type -> Type

Methods

from :: EvalStatus_ a b -> Rep (EvalStatus_ a b) x

to :: Rep (EvalStatus_ a b) x -> EvalStatus_ a b

Binary a => Binary (EvalStatus_ a b)

Defined in GHCi.Message

Methods

put :: EvalStatus_ a b -> Put

get :: Get (EvalStatus_ a b)

putList :: [EvalStatus_ a b] -> Put

type Rep (EvalStatus_ a b)

Defined in GHCi.Message

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

type EvalStatus a = EvalStatus_ a a

data EvalResult a

Constructors

EvalException SerializableException

EvalSuccess a

Instances

Show a => Show (EvalResult a)

Defined in GHCi.Message

Methods

showsPrec :: Int -> EvalResult a -> ShowS

show :: EvalResult a -> String

showList :: [EvalResult a] -> ShowS

Generic (EvalResult a)

Defined in GHCi.Message

Associated Types

type Rep (EvalResult a) :: Type -> Type

Methods

from :: EvalResult a -> Rep (EvalResult a) x

to :: Rep (EvalResult a) x -> EvalResult a

Binary a => Binary (EvalResult a)

Defined in GHCi.Message

Methods

put :: EvalResult a -> Put

get :: Get (EvalResult a)

putList :: [EvalResult a] -> Put

type Rep (EvalResult a)

Defined in GHCi.Message

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

data EvalExpr a

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)

Defined in GHCi.Message

Methods

showsPrec :: Int -> EvalExpr a -> ShowS

show :: EvalExpr a -> String

showList :: [EvalExpr a] -> ShowS

Generic (EvalExpr a)

Defined in GHCi.Message

Associated Types

type Rep (EvalExpr a) :: Type -> Type

Methods

from :: EvalExpr a -> Rep (EvalExpr a) x

to :: Rep (EvalExpr a) x -> EvalExpr a

Binary a => Binary (EvalExpr a)

Defined in GHCi.Message

Methods

put :: EvalExpr a -> Put

get :: Get (EvalExpr a)

putList :: [EvalExpr a] -> Put

type Rep (EvalExpr a)

Defined in GHCi.Message

type Rep (EvalExpr a) = D1 ('MetaData "EvalExpr" "GHCi.Message" "ghci-8.10.2" 'False) (C1 ('MetaCons "EvalThis" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a)) :+: C1 ('MetaCons "EvalApp" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (EvalExpr a)) :*: S1 ('MetaSel ('Nothing :: Maybe 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)

getClosure :: HscEnv -> ForeignHValue -> IO (GenClosure ForeignHValue)

seqHValue :: HscEnv -> ForeignHValue -> IO ()

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

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

RtsRevertCAFs :: Message ()

InitLinker :: Message ()

LookupSymbol :: String -> Message (Maybe (RemotePtr ()))

LookupClosure :: String -> Message (Maybe HValueRef)

LoadDLL :: String -> Message (Maybe String)

LoadArchive :: String -> Message ()

LoadObj :: String -> Message ()

UnloadObj :: String -> Message ()

AddLibrarySearchPath :: String -> Message (RemotePtr ())

RemoveLibrarySearchPath :: RemotePtr () -> Message Bool

ResolveObjs :: Message Bool

FindSystemLibrary :: String -> Message (Maybe String)

CreateBCOs :: [ByteString] -> 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 :: [HValueRef] -> Message ()

Release HValueRefs

AddSptEntry :: Fingerprint -> HValueRef -> Message ()

Add entries to the Static Pointer Table

MallocData :: ByteString -> Message (RemotePtr ())

Malloc some data and return a RemotePtr to it

MallocStrings :: [ByteString] -> Message [RemotePtr ()]

PrepFFI :: FFIConv -> [FFIType] -> FFIType -> Message (RemotePtr C_ffi_cif)

Calls prepareForeignCall

FreeFFI :: RemotePtr C_ffi_cif -> Message ()

Free data previously created by PrepFFI

MkConInfoTable :: Int -> Int -> Int -> Int -> ByteString -> Message (RemotePtr StgInfoTable)

Create an info table for a constructor

EvalStmt :: EvalOpts -> EvalExpr HValueRef -> Message (EvalStatus_ [HValueRef] [HValueRef])

Evaluate a statement

ResumeStmt :: EvalOpts -> RemoteRef (ResumeContext [HValueRef]) -> Message (EvalStatus_ [HValueRef] [HValueRef])

Resume evaluation of a statement after a breakpoint

AbandonStmt :: RemoteRef (ResumeContext [HValueRef]) -> Message ()

Abandon evaluation of a statement after a breakpoint

EvalString :: HValueRef -> Message (EvalResult String)

Evaluate something of type IO String

EvalStringToString :: HValueRef -> String -> Message (EvalResult String)

Evaluate something of type String -> IO String

EvalIO :: HValueRef -> Message (EvalResult ())

Evaluate something of type IO ()

MkCostCentres :: String -> [(String, String)] -> Message [RemotePtr CostCentre]

Create a set of CostCentres with the same module name

CostCentreStackInfo :: RemotePtr CostCentreStack -> Message [String]

Show a CostCentreStack as a [String]

NewBreakArray :: Int -> Message (RemoteRef BreakArray)

Create a new array of breakpoint flags

EnableBreakpoint :: RemoteRef BreakArray -> Int -> Bool -> Message ()

Enable a breakpoint

BreakpointStatus :: RemoteRef BreakArray -> Int -> Message Bool

Query the status of a breakpoint (True = enabled)

GetBreakpointVar :: HValueRef -> Int -> 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 :: RemoteRef (IORef QState) -> HValueRef -> THResultType -> Maybe Loc -> 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 :: RemoteRef (IORef QState) -> [RemoteRef (Q ())] -> Message (QResult ())

Run the given mod finalizers.

GetClosure :: HValueRef -> Message (GenClosure HValueRef)

Remote interface to GHC.Exts.Heap.getClosureData. This is used by the GHCi debugger to inspect values in the heap for :print and type reconstruction.

Seq :: HValueRef -> Message (EvalResult ())

Evaluate something. This is used to support :force in GHCi.

Instances

Show (Message a)

Defined in GHCi.Message

Methods

showsPrec :: Int -> Message a -> ShowS

show :: Message a -> String

showList :: [Message a] -> ShowS

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