Language.R.Instance

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.

The R monad

data R s a

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)

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)

Methods

fmap :: (a -> b) -> R s a -> R s b

(<$) :: a -> R s b -> R s a

Applicative (R s)

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)

Methods

liftIO :: IO a -> R s a

PrimMonad (R s)

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)

Methods

throwM :: Exception e => e -> R s a

MonadMask (R s)

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)

Methods

catch :: Exception e => R s a -> (e -> R s a) -> R s a

MonadR (R s)

Associated Types

data ExecContext (R s :: * -> *) :: *

Methods

io :: IO a -> R s a

acquire :: (* ~ s) V => SEXP s a -> R s (SEXP (Region (R s)) a)

getExecContext :: R s (ExecContext (R s))

unsafeRunWithExecContext :: R s a -> ExecContext (R s) -> IO a

(NFData c, Literal a a0, Literal b b0, Literal c c0) => Literal (a -> b -> R s c) ExtPtr

Methods

mkSEXPIO :: (a -> b -> R s c) -> IO (SEXP V ExtPtr)

fromSEXP :: SEXP s ExtPtr -> a -> b -> R s c

(NFData b, Literal a a0, Literal b b0) => Literal (a -> R s b) ExtPtr

Methods

mkSEXPIO :: (a -> R s b) -> IO (SEXP V ExtPtr)

fromSEXP :: SEXP s ExtPtr -> a -> R s b

(NFData a1, Literal a2 i1, Literal a3 i2, Literal a4 i3, Literal a1 i4) => Literal (a2 -> a3 -> a4 -> R s a1) ExtPtr

Methods

mkSEXPIO :: (a2 -> a3 -> a4 -> R s a1) -> IO (SEXP V ExtPtr)

fromSEXP :: SEXP s ExtPtr -> a2 -> a3 -> a4 -> R s a1

(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

Methods

mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> R s a1) -> IO (SEXP V ExtPtr)

fromSEXP :: SEXP s ExtPtr -> a2 -> a3 -> a4 -> a5 -> R s a1

(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

Methods

mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> R s a1) -> IO (SEXP V ExtPtr)

fromSEXP :: SEXP s ExtPtr -> a2 -> a3 -> a4 -> a5 -> a6 -> R s a1

(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

Methods

mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> R s a1) -> IO (SEXP V ExtPtr)

fromSEXP :: SEXP s ExtPtr -> a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> R s a1

(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

Methods

mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> R s a1) -> IO (SEXP V ExtPtr)

fromSEXP :: SEXP s ExtPtr -> a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> R s a1

(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

Methods

mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> R s a1) -> IO (SEXP V ExtPtr)

fromSEXP :: SEXP s ExtPtr -> a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> R s a1

(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

Methods

mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> R s a1) -> IO (SEXP V ExtPtr)

fromSEXP :: SEXP s ExtPtr -> a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> R s a1

(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

Methods

mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> R s a1) -> IO (SEXP V ExtPtr)

fromSEXP :: SEXP s ExtPtr -> a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> R s a1

(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

Methods

mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> a12 -> R s a1) -> IO (SEXP V ExtPtr)

fromSEXP :: SEXP s ExtPtr -> a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> a12 -> R s a1

(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

Methods

mkSEXPIO :: (a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> a12 -> a13 -> R s a1) -> IO (SEXP V ExtPtr)

fromSEXP :: SEXP s ExtPtr -> a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 -> a11 -> a12 -> a13 -> R s a1

(NFData a, Literal a b) => Literal (R s a) ExtPtr

Methods

mkSEXPIO :: R s a -> IO (SEXP V ExtPtr)

fromSEXP :: SEXP s ExtPtr -> R s a

type PrimState (R s)

type PrimState (R s) = s

data ExecContext (R s)

data ExecContext (R s) = ExecContext (IORef Int)

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

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

R instance creation

data Config

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

Methods

mempty :: Config

mappend :: Config -> Config -> Config

mconcat :: [Config] -> Config

Default Config

Methods

def :: Config

defaultConfig :: Config

Default argument to pass to initialize.

withEmbeddedR :: Config -> IO a -> IO a

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

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

Finalize an R instance.