r_session: External R Session

Description Super class Methods Examples

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

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

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

Returns

A list with the following entries.


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


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:


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. Event types:


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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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 documentation built on April 14, 2020, 7:54 p.m.