wrap:sentence

```{r, setup, include = FALSE}

Install the stable version from CRAN:

```{r, asciicast-setup, eval = FALSE, cache = FALSE}

Install the development version from GitHub:

```{r, asciicast-setup2, eval = FALSE, cache = FALSE}

Use`r()` to run an R function in a new R process.

The results are passed back seamlessly:

```{asciicast simple}

This is often necessary as these arguments are explicitly copied to the child process, whereas the evaluated function cannot refer to variables in the parent.

For example, the following does not work:

```{asciicast passargsfail}

But this does:

```{asciicast, passargsok}

You can use any R package in the child process, just make sure to refer to it explicitly with the`::` operator.

For example, the following code creates an[igraph](https://github.com/igraph/rigraph) graph in the child, and calculates some metrics of it.

```{asciicast packages}

callr copies errors from the child process back to the main R session:

```{asciicast error1}

callr sets the`.Last.error` variable, and after an error you can inspect this for more details about the error, including stack traces both from the main R process and the subprocess.

```{asciicast error2-2}

By default, the standard output and error of the child is lost, but you can request callr to redirect them to files, and then inspect the files in the parent:

```{asciicast io, results = "hide"}

```{asciicast io-2}

`r_bg()` is similar to`r()` but it starts the R process in the background.

It returns an`r_process` R6 object, that provides a rich API:

```{asciicast bg}

This is a list of all`r_process` methods:

```{asciicast, bg-methods}

It returns as soon as one process has generated an event, or if its timeout has expired.

The timeout is in milliseconds.

```{asciicast poll}

```{asciicast poll-2}

```{asciicast poll-3}

```{asciicast poll-4}

`r_session` is another`processx::process` subclass that represents a persistent background R session:

```{asciicast rsession}

Once an R session is done with an asynchronous computation, its`poll_process()` method returns`"ready"` and the`r_session$read()` method can read out the result.

```{asciicast rsession2}

```{asciicast rsession2-2}

```{asciicast rsession-4}

```{asciicast rsession-5}

The`rcmd()` function calls an`R CMD` command.

For example, you can call`R CMD INSTALL`,`R CMD check` or`R CMD config` this way:

```{asciicast rcmd}

-[Features](#features)

-[Installation](#installation)

-[Synchronous, one-off R processes](#synchronous-one-off-r-processes)

-[Passing arguments](#passing-arguments)

-[Using packages](#using-packages)

-[Error handling](#error-handling)

-[Standard output and error](#standard-output-and-error)

-[Background R processes](#background-r-processes)

-[Multiple background R processes and

-[Persistent R sessions](#persistent-r-sessions)

-[Running`R CMD` commands](#running-r-cmd-commands)

-[Code of Conduct](#code-of-conduct)

-[Features](#features)

-[Installation](#installation)

-[Synchronous, one-off R processes](#synchronous-one-off-r-processes)

-[Passing arguments](#passing-arguments)

-[Using packages](#using-packages)

-[Error handling](#error-handling)

-[Standard output and error](#standard-output-and-error)

-[Background R processes](#background-r-processes)

-[Multiple background R processes and

-[Persistent R sessions](#persistent-r-sessions)

-[Running`R CMD` commands](#running-r-cmd-commands)

-[Configuration](#configuration)

-[Environment variables](#environment-variables)

-[Code of Conduct](#code-of-conduct)

- Calls an R function, with arguments, in a subprocess.

- Copies function arguments to the subprocess and copies the return

value of the function back, seamlessly.

- Copies error objects back from the subprocess, including a stack

trace.

- Shows and/or collects the standard output and standard error of the

subprocess.

- Supports both one-off and persistent R subprocesses.

- Calls the function synchronously or asynchronously (in the

background).

- Can call`R CMD` commands, synchronously or asynchronously.

- Can call R scripts, synchronously or asynchronously.

- Provides extensible`r_process`,`rcmd_process` and`rscript_process`

R6 classes, based on`processx::process`.

-Calls an R function, with arguments, in a subprocess.

-Copies function arguments to the subprocess and copies the return

value of the function back, seamlessly.

-Copies error objects back from the subprocess, including a stack

trace.

-Shows and/or collects the standard output and standard error of the

subprocess.

-Supports both one-off and persistent R subprocesses.

-Calls the function synchronously or asynchronously (in the

background).

-Can call`R CMD` commands, synchronously or asynchronously.

-Can call R scripts, synchronously or asynchronously.

-Provides extensible`r_process`,`rcmd_process` and

`rscript_process`R6 classes, based on`processx::process`.

new`get_result()` method, to retrieve the R object returned by the

function call. Some of the handiest methods are:

-`get_exit_status()` to query the exit status of a finished process.

-`get_result()` to collect the return value of the R function call.

-`interrupt()` to send an interrupt to the process. This is equivalent

to a`CTRL+C` key press, and the R process might ignore it.

-`is_alive()` to check if the process is alive.

-`kill()` to terminate the process.

-`poll_io()` to wait for any standard output, standard error, or the

completion of the process, with a timeout.

-`read_*()` to read the standard output or error.

-`suspend()` and`resume()` to stop and continue a process.

-`wait()` to wait for the completion of the process, with a timeout.

-`get_exit_status()` to query the exit status of a finished process.

-`get_result()` to collect the return value of the R function call.

-`interrupt()` to send an interrupt to the process. This is

equivalent to a`CTRL+C` key press, and the R process might ignore

it.

-`is_alive()` to check if the process is alive.

-`kill()` to terminate the process.

-`poll_io()` to wait for any standard output, standard error, or the

completion of the process, with a timeout.

-`read_*()` to read the standard output or error.

-`suspend()` and`resume()` to stop and continue a process.

-`wait()` to wait for the completion of the process, with a timeout.

*`CALLR_NO_TEMP_DLLS`: If`true`, then callr does not use a temporary

directory to copy the client DLL files from, in the subprocess. By

default callr copies the DLL file that drives the callr subprocess into

a temporary directory and loads it from there. This is mainly to avoid

locking a DLL file in the package library, on Windows. If this default

causes issues for you, set it to`true`, and then callr will use the DLL

file from the installed processx package. See also

https://github.com/r-lib/callr/issues/273.

-`CALLR_NO_TEMP_DLLS`: If`true`, then callr does not use a temporary

directory to copy the client DLL files from, in the subprocess. By

default callr copies the DLL file that drives the callr subprocess

intoa temporary directory and loads it from there. This is mainly

to avoidlocking a DLL file in the package library, on Windows. If

this defaultcauses issues for you, set it to`true`, and then callr

will use the DLLfile from the installed processx package. See also

<https://github.com/r-lib/callr/issues/273>.