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

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.

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

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

#### Arguments

timeout

Timeout period in milliseconds.

#### Returns

Character string "ready" or "timeout".

### Method get_state()

Return the state of the R session.

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

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

On callr version 3.8.0 and above, you need to set the callr.traceback option to TRUE (in the main process) to make the subprocess save the trace on error. This is because saving the trace can be costly for large objects passed as arguments.

### Method attach()

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

### Method print()

Print method for an r_session.

#### Arguments

deep

Whether to make a deep clone.

## Examples

if (FALSE) {
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()