Copyright	(C) 2013 Amgen Inc.
Safe Haskell	None
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

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

Monad (R s) Source #
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 # fail :: String -> R s a #
Functor (R s) Source #
Methods fmap :: (a -> b) -> R s a -> R s b # (<$) :: a -> R s b -> R s a #
Applicative (R s) Source #
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 #
MonadIO (R s) Source #
Methods liftIO :: IO a -> R s a #
PrimMonad (R s) Source #
Associated Types type PrimState (R s :: * -> ) :: Methods primitive :: (State# (PrimState (R s)) -> (#TupleRep [RuntimeRep], LiftedRep, State# (PrimState (R s)), a#)) -> R s a
MonadThrow (R s) Source #
Methods throwM :: Exception e => e -> R s a
MonadMask (R s) Source #
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
MonadCatch (R s) Source #
Methods catch :: Exception e => R s a -> (e -> R s a) -> R s a
MonadR (R s) Source #
Associated Types data ExecContext (R s :: * -> ) :: Source # Methods io :: IO a -> R s a Source # acquire :: (* ~ s) V => SEXP s 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 #
(NFData c, Literal a a0, Literal b b0, Literal c c0) => Literal (a -> b -> R s c) ExtPtr Source #
Methods mkSEXPIO :: (a -> b -> R s c) -> IO (SEXP V ExtPtr) Source # fromSEXP :: SEXP s ExtPtr -> a -> b -> R s c Source #
(NFData b, Literal a a0, Literal b b0) => Literal (a -> R s b) ExtPtr Source #
Methods mkSEXPIO :: (a -> R s b) -> IO (SEXP V ExtPtr) Source # fromSEXP :: SEXP s ExtPtr -> a -> R s b Source #
(NFData a1, Literal a2 i1, Literal a3 i2, Literal a4 i3, Literal a1 i4) => Literal (a2 -> a3 -> a4 -> R s a1) ExtPtr Source #
Methods mkSEXPIO :: (a2 -> a3 -> a4 -> R s a1) -> IO (SEXP V ExtPtr) Source # fromSEXP :: SEXP s 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 #
Methods mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> R s a1) -> IO (SEXP V ExtPtr) Source # fromSEXP :: SEXP s 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 #
Methods mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> R s a1) -> IO (SEXP V ExtPtr) Source # fromSEXP :: SEXP s 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 #
Methods mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> R s a1) -> IO (SEXP V ExtPtr) Source # fromSEXP :: SEXP s 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 #
Methods mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> R s a1) -> IO (SEXP V ExtPtr) Source # fromSEXP :: SEXP s 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 #
Methods mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> R s a1) -> IO (SEXP V ExtPtr) Source # fromSEXP :: SEXP s 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 #
Methods mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> R s a1) -> IO (SEXP V ExtPtr) Source # fromSEXP :: SEXP s 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 #
Methods mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> R s a1) -> IO (SEXP V ExtPtr) Source # fromSEXP :: SEXP s 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 #
Methods mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> a12 -> R s a1) -> IO (SEXP V ExtPtr) Source # fromSEXP :: SEXP s 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 #
Methods mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> a12 -> a13 -> R s a1) -> IO (SEXP V ExtPtr) Source # fromSEXP :: SEXP s ExtPtr -> a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> a12 -> a13 -> R s a1 Source #
(NFData a, Literal a b) => Literal (R s a) ExtPtr Source #
Methods mkSEXPIO :: R s a -> IO (SEXP V ExtPtr) Source # fromSEXP :: SEXP s ExtPtr -> R s a Source #
type PrimState (R s) Source #
type PrimState (R s) = s
data ExecContext (R s) Source #
data ExecContext (R s) = ExecContext (IORef Int)

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).

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

Monoid Config Source #
Methods mempty :: Config # mappend :: Config -> Config -> Config # mconcat :: [Config] -> Config #
Default Config Source #
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.