Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!
Get Started for Free

r_session

External R Session

Description

A permanent R session that runs in the background. This is an R6 class that extends the processx::process class.

The process is started at the creation of the object, and then it can be used to evaluate R function calls, one at a time.

Super class

processx::process -> r_session

Public fields

status

Status codes returned by read().

Methods

Public methods

Inherited methods

Method new()

creates a new R background process. It can wait for the process to start up (wait = TRUE), or return immediately, i.e. before the process is actually ready to run. In the latter case you may call the poll_process() method to make sure it is ready.

Usage
r_session$new(options = r_session_options(), wait = TRUE, wait_timeout = 3000)
Arguments
options

A list of options created via r_session_options().

wait

Whether to wait for the R process to start and be ready for running commands.

wait_timeout

Timeout for waiting for the R process to start, in milliseconds.

Returns

An r_session object.

Method run()

Similar to r(), but runs the function in a permanent background R session. It throws an error if the function call generated an error in the child process.

Usage
r_session$run(func, args = list(), package = FALSE)
Arguments
func

Function object to call in the background R process. Please read the notes for the similar argument of r().

args

Arguments to pass to the function. Must be a list.

package

Whether to keep the environment of func when passing it to the other package. Possible values are:

  • FALSE: reset the environment to .GlobalEnv. This is the default.

  • TRUE: keep the environment as is.

  • pkg: set the environment to the pkg package namespace.

Returns

The return value of the R expression.

Method run_with_output()

Similar to $run(), but returns the standard output and error of the child process as well. It does not throw on errors, but returns a non-NULL error member in the result list.

Usage
r_session$run_with_output(func, args = list(), package = FALSE)
Arguments
func

Function object to call in the background R process. Please read the notes for the similar argument of r().

args

Arguments to pass to the function. Must be a list.

package

Whether to keep the environment of func when passing it to the other package. Possible values are:

  • FALSE: reset the environment to .GlobalEnv. This is the default.

  • TRUE: keep the environment as is.

  • pkg: set the environment to the pkg package namespace.

Returns

A list with the following entries.

  • result: The value returned by func. On error this is NULL.

  • stdout: The standard output of the process while evaluating

  • stderr: The standard error of the process while evaluating the func call.

  • error: On error it contains an error object, that contains the error thrown in the subprocess. Otherwise it is NULL.

  • code, message: These fields are used by call internally and you can ignore them.

Method call()

Starts running a function in the background R session, and returns immediately. To check if the function is done, call the poll_process() method.

Usage
r_session$call(func, args = list(), package = FALSE)
Arguments
func

Function object to call in the background R process. Please read the notes for the similar argument of r().

args

Arguments to pass to the function. Must be a list.

package

Whether to keep the environment of func when passing it to the other package. Possible values are:

  • FALSE: reset the environment to .GlobalEnv. This is the default.

  • TRUE: keep the environment as is.

  • pkg: set the environment to the pkg package namespace.

Method poll_process()

Poll the R session with a timeout. If the session has finished the computation, it returns with "ready". If the timeout is reached, it returns with "timeout".

Usage
r_session$poll_process(timeout)
Arguments
timeout

Timeout period in milliseconds.

Returns

Character string "ready" or "timeout".

Method get_state()

Return the state of the R session.

Usage
r_session$get_state()
Returns

Possible values:

  • "starting": starting up,

  • "idle": ready to compute,

  • "busy": computing right now,

  • "finished": the R process has finished.

Method get_running_time()

Returns the elapsed time since the R process has started, and the elapsed time since the current computation has started. The latter is NA if there is no active computation.

Usage
r_session$get_running_time()
Returns

Named vector of POSIXct objects. The names are "total" and "current".

Method read()

Reads an event from the child process, if there is one available. Events might signal that the function call has finished, or they can be progress report events.

This is a low level function that you only need to use if you want to process events (messages) from the R session manually.

Usage
r_session$read()
Returns

NULL if no events are available. Otherwise a named list, which is also a callr_session_result object. The list always has a code entry which is the type of the event. See also r_session$public_fields$status for symbolic names of the event types.

  • 200: (DONE) The computation is done, and the event includes the result, in the same form as for the run() method.

  • 201: (STARTED) An R session that was in 'starting' state is ready to go.

  • 202: (ATTACH_DONE) Used by the attach() method.

  • 301: (MSG) A message from the subprocess. The message is a condition object with class callr_message. (It typically has other classes, e.g. cli_message for output from the cli package.)

  • 500: (EXITED) The R session finished cleanly. This means that the evaluated expression quit R.

  • 501: (CRASHED) The R session crashed or was killed.

  • 502: (CLOSED) The R session closed its end of the connection that callr uses for communication.

Method close()

Terminate the current computation and the R process. The session object will be in "finished" state after this.

Usage
r_session$close(grace = 1000)
Arguments
grace

Grace period in milliseconds, to wait for the subprocess to exit cleanly, after its standard input is closed. If the process is still running after this period, it will be killed.

Method traceback()

The traceback() method can be used after an error in the R subprocess. It is equivalent to the base::traceback() call, in the subprocess.

Usage
r_session$traceback()
Returns

The same output as from base::traceback()

Method debug()

Interactive debugger to inspect the dumped frames in the subprocess, after an error. See more at r_session_debug.

Usage
r_session$debug()

Method attach()

Experimental function that provides a REPL (Read-Eval-Print-Loop) to the subprocess.

Usage
r_session$attach()

Method finalize()

Finalizer that is called when garbage collecting an r_session object, to clean up temporary files.

Usage
r_session$finalize()

Method print()

Print method for an r_session.

Usage
r_session$print(...)
Arguments
...

Arguments are not used currently.

Method clone()

The objects of this class are cloneable with this method.

Usage
r_session$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

Examples

rs <- r_ression$new()

rs$run(function() 1 + 2)

rs$call(function() Sys.sleep(1))
rs$get_state()

rs$poll_process(-1)
rs$get_state()
rs$read()
callr

Call R from R

v3.7.0
MIT + file LICENSE
Authors
Gábor Csárdi [aut, cre, cph] (<https://orcid.org/0000-0001-7098-9676>), Winston Chang [aut], RStudio [cph, fnd], Mango Solutions [cph, fnd]
Initial release

We don't support your browser anymore

Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.