Home

Awesome

<!-- README.md is generated from README.Rmd. Please edit that file -->

callr

Call R from R

<!-- badges: start -->

lifecycle R-CMD-check CRAN Posit mirror downloads Codecov test coverage

<!-- badges: end -->

It is sometimes useful to perform a computation in a separate R process, without affecting the current R process at all. This packages does exactly that.


Features

Installation

Install the stable version from CRAN:

install.packages("callr")

Install the development version from GitHub:

pak::pak("r-lib/callr")

Synchronous, one-off R processes

Use r() to run an R function in a new R process. The results are passed back seamlessly:

callr::r(function() var(iris[, 1:4]))
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/simple-dark.svg"> <img src="man/figures/simple.svg" /> </picture>

Passing arguments

You can pass arguments to the function by setting args to the list of arguments. 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:

mycars <- cars
callr::r(function() summary(mycars))
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/passargsfail-dark.svg"> <img src="man/figures/passargsfail.svg" /> </picture>

But this does:

mycars <- cars
callr::r(function(x) summary(x), args = list(mycars))
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/passargsok-dark.svg"> <img src="man/figures/passargsok.svg" /> </picture>

Note that the arguments will be serialized and saved to a file, so if they are large R objects, it might take a long time for the child process to start up.

Using packages

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 graph in the child, and calculates some metrics of it.

callr::r(function() { g <- igraph::sample_gnp(1000, 4/1000); igraph::diameter(g) })
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/packages-dark.svg"> <img src="man/figures/packages.svg" /> </picture>

Error handling

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

callr::r(function() 1 + "A")
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/error1-dark.svg"> <img src="man/figures/error1.svg" /> </picture> 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.
.Last.error
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/error2-2-dark.svg"> <img src="man/figures/error2-2.svg" /> </picture>

The error objects has two parts. The first belongs to the main process, and the second belongs to the subprocess.

.Last.error also includes a stack trace, that includes both the main R process and the subprocess:

The top part of the trace contains the frames in the main process, and the bottom part contains the frames in the subprocess, starting with the anonymous function.

Standard output and error

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:

x <- callr::r(function() { print("hello world!"); message("hello again!") },
  stdout = "/tmp/out", stderr = "/tmp/err"
)
readLines("/tmp/out")
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/io-dark.svg"> <img src="man/figures/io.svg" /> </picture>
readLines("/tmp/err")
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/io-2-dark.svg"> <img src="man/figures/io-2.svg" /> </picture>

With the stdout option, the standard output is collected and can be examined once the child process finished. The show = TRUE options will also show the output of the child, as it is printed, on the console of the parent.

Background R processes

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:

rp <- callr::r_bg(function() Sys.sleep(.2))
rp
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/bg-dark.svg"> <img src="man/figures/bg.svg" /> </picture>

This is a list of all r_process methods:

ls(rp)
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/bg-methods-dark.svg"> <img src="man/figures/bg-methods.svg" /> </picture>

These include all methods of the processx::process superclass and the new get_result() method, to retrieve the R object returned by the function call. Some of the handiest methods are:

Multiple background R processes and poll()

Multiple background R processes are best managed with the processx::poll() function that waits for events (standard output/error or termination) from multiple processes. It returns as soon as one process has generated an event, or if its timeout has expired. The timeout is in milliseconds.

rp1 <- callr::r_bg(function() { Sys.sleep(1/2); "1 done" })
rp2 <- callr::r_bg(function() { Sys.sleep(1/1000); "2 done" })
processx::poll(list(rp1, rp2), 1000)
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/poll-dark.svg"> <img src="man/figures/poll.svg" /> </picture>
rp2$get_result()
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/poll-2-dark.svg"> <img src="man/figures/poll-2.svg" /> </picture>
processx::poll(list(rp1), 1000)
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/poll-3-dark.svg"> <img src="man/figures/poll-3.svg" /> </picture>
rp1$get_result()
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/poll-4-dark.svg"> <img src="man/figures/poll-4.svg" /> </picture>

Persistent R sessions

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

rs <- callr::r_session$new()
rs
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/rsession-dark.svg"> <img src="man/figures/rsession.svg" /> </picture>

r_session$run() is a synchronous call, that works similarly to r(), but uses the persistent session. r_session$call() starts the function call and returns immediately. The r_session$poll_process() method or processx::poll() can then be used to wait for the completion or other events from one or more R sessions, R processes or other processx::process objects.

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.

rs <- callr::r_session$new()
rs$run(function() runif(10))
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/rsession2-dark.svg"> <img src="man/figures/rsession2.svg" /> </picture>
rs$call(function() rnorm(10))
rs
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/rsession2-2-dark.svg"> <img src="man/figures/rsession2-2.svg" /> </picture>
rs$poll_process(2000)
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/rsession-4-dark.svg"> <img src="man/figures/rsession-4.svg" /> </picture>
rs$read()
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/rsession-5-dark.svg"> <img src="man/figures/rsession-5.svg" /> </picture>

Running R CMD commands

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:

callr::rcmd("config", "CC")
<picture> <source media="(prefers-color-scheme: dark)" srcset="man/figures/rcmd-dark.svg"> <img src="man/figures/rcmd.svg" /> </picture>

This returns a list with three components: the standard output, the standard error, and the exit (status) code of the R CMD command.

Configuration

Environment variables

Code of Conduct

Please note that the callr project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.