Copyright	(C) 2013 Amgen Inc.
Safe Haskell	Safe-Inferred
Language	Haskell2010

Language.R.Instance

Contents

The R monad
R instance creation

Description

Interaction with an instance of R. The interface in this module allows for instantiating an arbitrary number of concurrent R sessions, even though currently the R library only allows for one global instance, for forward compatibility.

The R monad defined here serves to give static guarantees that an instance is only ever used after it has been initialized and before it is finalized. Doing otherwise should result in a type error. This is done in the same way that the ST monad encapsulates side effects: by assigning a rank-2 type to the only run function for the monad.

This module is intended to be imported qualified.

Synopsis

data R s a
runRegion :: NFData a => (forall s. R s a) -> IO a
unsafeRunRegion :: NFData a => R s a -> IO a
data Config = Config {
- configProgName :: Last String
- configArgs :: [String]
- configSignalHandlers :: Last Bool
}
defaultConfig :: Config
withEmbeddedR :: Config -> IO a -> IO a
initialize :: Config -> IO ()
finalize :: IO ()

The R monad

data R s a Source #

The R monad, for sequencing actions interacting with a single instance of the R interpreter, much as the IO monad sequences actions interacting with the real world. The R monad embeds the IO monad, so all IO actions can be lifted to R actions.

Instances

Instances details

MonadFail (R s) Source #
Instance details Defined in Language.R.Instance Methods fail :: String -> R s a #
MonadIO (R s) Source #
Instance details Defined in Language.R.Instance Methods liftIO :: IO a -> R s a #
Applicative (R s) Source #
Instance details Defined in Language.R.Instance Methods pure :: a -> R s a # (<>) :: R s (a -> b) -> R s a -> R s b # liftA2 :: (a -> b -> c) -> R s a -> R s b -> R s c # (>) :: R s a -> R s b -> R s b # (<*) :: R s a -> R s b -> R s a #
Functor (R s) Source #
Instance details Defined in Language.R.Instance Methods fmap :: (a -> b) -> R s a -> R s b # (<$) :: a -> R s b -> R s a #
Monad (R s) Source #
Instance details Defined in Language.R.Instance Methods (>>=) :: R s a -> (a -> R s b) -> R s b # (>>) :: R s a -> R s b -> R s b # return :: a -> R s a #
MonadCatch (R s) Source #
Instance details Defined in Language.R.Instance Methods catch :: Exception e => R s a -> (e -> R s a) -> R s a #
MonadMask (R s) Source #
Instance details Defined in Language.R.Instance Methods mask :: ((forall a. R s a -> R s a) -> R s b) -> R s b # uninterruptibleMask :: ((forall a. R s a -> R s a) -> R s b) -> R s b # generalBracket :: R s a -> (a -> ExitCase b -> R s c) -> (a -> R s b) -> R s (b, c) #
MonadThrow (R s) Source #
Instance details Defined in Language.R.Instance Methods throwM :: Exception e => e -> R s a #
MonadR (R s) Source #
Instance details Defined in Language.R.Instance Associated Types data ExecContext (R s) Source # Methods io :: IO a -> R s a Source # acquire :: forall s0 (a :: SEXPTYPE). s0 ~ V => SEXP s0 a -> R s (SEXP (Region (R s)) a) Source # getExecContext :: R s (ExecContext (R s)) Source # unsafeRunWithExecContext :: R s a -> ExecContext (R s) -> IO a Source #
PrimMonad (R s) Source #
Instance details Defined in Language.R.Instance Associated Types type PrimState (R s) # Methods primitive :: (State# (PrimState (R s)) -> (# State# (PrimState (R s)), a #)) -> R s a #
(NFData a, Literal a b) => Literal (R s a) 'ExtPtr Source #
Instance details Defined in Language.R.Literal Methods mkSEXPIO :: R s a -> IO (SEXP V 'ExtPtr) Source # fromSEXP :: SEXP s0 'ExtPtr -> R s a Source #
(NFData b, Literal a a0, Literal b b0) => Literal (a -> R s b) 'ExtPtr Source #
Instance details Defined in Language.R.Literal Methods mkSEXPIO :: (a -> R s b) -> IO (SEXP V 'ExtPtr) Source # fromSEXP :: SEXP s0 'ExtPtr -> a -> R s b Source #
(NFData c, Literal a a0, Literal b b0, Literal c c0) => Literal (a -> b -> R s c) 'ExtPtr Source #
Instance details Defined in Language.R.Literal Methods mkSEXPIO :: (a -> b -> R s c) -> IO (SEXP V 'ExtPtr) Source # fromSEXP :: SEXP s0 'ExtPtr -> a -> b -> R s c Source #
(NFData a1, Literal a2 i1, Literal a3 i2, Literal a4 i3, Literal a1 i4) => Literal (a2 -> a3 -> a4 -> R s a1) 'ExtPtr Source #
Instance details Defined in Language.R.Literal Methods mkSEXPIO :: (a2 -> a3 -> a4 -> R s a1) -> IO (SEXP V 'ExtPtr) Source # fromSEXP :: SEXP s0 'ExtPtr -> a2 -> a3 -> a4 -> R s a1 Source #
(NFData a1, Literal a2 i1, Literal a3 i2, Literal a4 i3, Literal a5 i4, Literal a1 i5) => Literal (a2 -> a3 -> a4 -> a5 -> R s a1) 'ExtPtr Source #
Instance details Defined in Language.R.Literal Methods mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> R s a1) -> IO (SEXP V 'ExtPtr) Source # fromSEXP :: SEXP s0 'ExtPtr -> a2 -> a3 -> a4 -> a5 -> R s a1 Source #
(NFData a1, Literal a2 i1, Literal a3 i2, Literal a4 i3, Literal a5 i4, Literal a6 i5, Literal a1 i6) => Literal (a2 -> a3 -> a4 -> a5 -> a6 -> R s a1) 'ExtPtr Source #
Instance details Defined in Language.R.Literal Methods mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> R s a1) -> IO (SEXP V 'ExtPtr) Source # fromSEXP :: SEXP s0 'ExtPtr -> a2 -> a3 -> a4 -> a5 -> a6 -> R s a1 Source #
(NFData a1, Literal a2 i1, Literal a3 i2, Literal a4 i3, Literal a5 i4, Literal a6 i5, Literal a7 i6, Literal a1 i7) => Literal (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> R s a1) 'ExtPtr Source #
Instance details Defined in Language.R.Literal Methods mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> R s a1) -> IO (SEXP V 'ExtPtr) Source # fromSEXP :: SEXP s0 'ExtPtr -> a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> R s a1 Source #
(NFData a1, Literal a2 i1, Literal a3 i2, Literal a4 i3, Literal a5 i4, Literal a6 i5, Literal a7 i6, Literal a8 i7, Literal a1 i8) => Literal (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> R s a1) 'ExtPtr Source #
Instance details Defined in Language.R.Literal Methods mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> R s a1) -> IO (SEXP V 'ExtPtr) Source # fromSEXP :: SEXP s0 'ExtPtr -> a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> R s a1 Source #
(NFData a1, Literal a2 i1, Literal a3 i2, Literal a4 i3, Literal a5 i4, Literal a6 i5, Literal a7 i6, Literal a8 i7, Literal a9 i8, Literal a1 i9) => Literal (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> R s a1) 'ExtPtr Source #
Instance details Defined in Language.R.Literal Methods mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> R s a1) -> IO (SEXP V 'ExtPtr) Source # fromSEXP :: SEXP s0 'ExtPtr -> a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> R s a1 Source #
(NFData a1, Literal a2 i1, Literal a3 i2, Literal a4 i3, Literal a5 i4, Literal a6 i5, Literal a7 i6, Literal a8 i7, Literal a9 i8, Literal a10 i9, Literal a1 i10) => Literal (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> R s a1) 'ExtPtr Source #
Instance details Defined in Language.R.Literal Methods mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> R s a1) -> IO (SEXP V 'ExtPtr) Source # fromSEXP :: SEXP s0 'ExtPtr -> a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> R s a1 Source #
(NFData a1, Literal a2 i1, Literal a3 i2, Literal a4 i3, Literal a5 i4, Literal a6 i5, Literal a7 i6, Literal a8 i7, Literal a9 i8, Literal a10 i9, Literal a11 i10, Literal a1 i11) => Literal (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> R s a1) 'ExtPtr Source #
Instance details Defined in Language.R.Literal Methods mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> R s a1) -> IO (SEXP V 'ExtPtr) Source # fromSEXP :: SEXP s0 'ExtPtr -> a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> R s a1 Source #
(NFData a1, Literal a2 i1, Literal a3 i2, Literal a4 i3, Literal a5 i4, Literal a6 i5, Literal a7 i6, Literal a8 i7, Literal a9 i8, Literal a10 i9, Literal a11 i10, Literal a12 i11, Literal a1 i12) => Literal (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> a12 -> R s a1) 'ExtPtr Source #
Instance details Defined in Language.R.Literal Methods mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> a12 -> R s a1) -> IO (SEXP V 'ExtPtr) Source # fromSEXP :: SEXP s0 'ExtPtr -> a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> a12 -> R s a1 Source #
(NFData a1, Literal a2 i1, Literal a3 i2, Literal a4 i3, Literal a5 i4, Literal a6 i5, Literal a7 i6, Literal a8 i7, Literal a9 i8, Literal a10 i9, Literal a11 i10, Literal a12 i11, Literal a13 i12, Literal a1 i13) => Literal (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> a12 -> a13 -> R s a1) 'ExtPtr Source #
Instance details Defined in Language.R.Literal Methods mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> a12 -> a13 -> R s a1) -> IO (SEXP V 'ExtPtr) Source # fromSEXP :: SEXP s0 'ExtPtr -> a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> a12 -> a13 -> R s a1 Source #
newtype ExecContext (R s) Source #
Instance details Defined in Language.R.Instance newtype ExecContext (R s) = ExecContext (IORef Int)
type PrimState (R s) Source #
Instance details Defined in Language.R.Instance type PrimState (R s) = s

runRegion :: NFData a => (forall s. R s a) -> IO a Source #

Run an R action in the global R instance from the IO monad. This action provides no static guarantees that the R instance was indeed initialized and has not yet been finalized. Make sure to call it within the scope of withEmbeddedR.

runRegion m fully evaluates the result of action m, to ensure that no thunks hold onto resources in a way that would extrude the scope of the region. This means that the result must be first-order data (i.e. not a function).

throws Error. Generaly any R function may throw RError that is safe to be cached and computation can proceed. However RError will cancel entire R block. So in order to catch exception in more fine grained way one has to use function tryCatch inside R block.

unsafeRunRegion :: NFData a => R s a -> IO a Source #

R instance creation

data Config Source #

Configuration options for the R runtime. Configurations form monoids, so arguments can be accumulated left-to-right through monoidal composition.

Constructors

Config

Fields

configProgName :: Last String
Program name. If Nothing then the value of getProgName will be used.
configArgs :: [String]
Command-line arguments.
configSignalHandlers :: Last Bool
Set to True if you're happy to let R install its own signal handlers during initialization. By default R sets following signal handlers:
- SIGPIPE - ignore signal;
- SIGUSR1 - save workspace and terminate program;
- SIGUSR2 - terminate program without saving workspace;
- SIGINT - cancel execution of the current function.
- N.B.* When program is terminated, haskell runtime will not have any chances to run any exception handlers or finalizers.

Instances

Instances details

Monoid Config Source #
Instance details Defined in Language.R.Instance Methods mempty :: Config # mappend :: Config -> Config -> Config # mconcat :: [Config] -> Config #
Semigroup Config Source #
Instance details Defined in Language.R.Instance Methods (<>) :: Config -> Config -> Config # sconcat :: NonEmpty Config -> Config # stimes :: Integral b => b -> Config -> Config #
Default Config Source #
Instance details Defined in Language.R.Instance Methods def :: Config #

defaultConfig :: Config Source #

Default argument to pass to initialize.

withEmbeddedR :: Config -> IO a -> IO a Source #

Initialize a new instance of R, execute actions that interact with the R instance and then finalize the instance. This is typically called at the very beginning of the main function of the program.

main = withEmbeddedR $ do {...}

Note that R does not currently support reinitialization after finalization, so this function should be called only once during the lifetime of the program (see srcunixsystem.c:Rf_initialize() in the R source code).

initialize :: Config -> IO () Source #

Create a new embedded instance of the R interpreter. Only works from the main thread of the program. That is, from the same thread of execution that the program's main function is running on. In GHCi, use -fno-ghci-sandbox to achieve this.

finalize :: IO () Source #

Finalize an R instance.