External R Session

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


r_session$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 rs$poll_process() to make sure it is ready.

rs$run() is similar to r(), but runs the function in the rs R session. It throws an error if the function call generated an error in the child process.

rs$run_with_output() is 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-zero error member in the result list.

rs$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.

rs$poll_process() polls 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".

rs$get_state() return the state of the R session. Possible values:

  • "starting": starting up,

  • "idle": ready to compute,

  • "busy": computing right now,

  • "finished": the R process has finished.

rs$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.

rs$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.

rs$close() terminates the current computation and the R process. The session object will be in "finished" state after this.

`rs$traceback() can be used after an error in the R subprocess. It is equivalent to the traceback() call, but it is performed in the subprocess.

rs$debug() is an interactive debugger to inspect the dumped frames in the subprocess, after an error. See more at r_session_debug.

rs$attach() is an experimental function that provides a REPL (Read-Eval-Print-Loop) to the subprocess.


rs <- r_session$new(options = r_session_options(), wait = TRUE,
                     wait_timeout = 3000)

rs$run(func, args = list()) rs$run_with_output(func, args = list()) rs$call(func, args = list())


rs$get_state() rs$get_running_time()

rs$read() rs$close(grace = 1000)

rs$traceback() rs$debug() rs$attach()


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

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

  • timeout: Timeout period in milliseconds.

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

  • r_session
rs <- r_ression$new()

rs$run(function() 1 + 2)

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

# }
Documentation reproduced from package callr, version 3.3.2, License: MIT + file LICENSE

Community examples

Looks like there are no examples yet.