126

callr

Call R from R

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.

Linux Build Status Windows Build status CRAN RStudio mirror downloads Coverage Status

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.

Installation

Install the stable version from CRAN:

install.packages("callr")

Install the development version from GitHub:

source("https://install-github.me/r-lib/callr")

Usage

Introduction

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

r(function() var(iris[, 1:4]))
 
#>              Sepal.Length Sepal.Width Petal.Length Petal.Width
#> Sepal.Length    0.6856935  -0.0424340    1.2743154   0.5162707
#> Sepal.Width    -0.0424340   0.1899794   -0.3296564  -0.1216394
#> Petal.Length    1.2743154  -0.3296564    3.1162779   1.2956094
#> Petal.Width     0.5162707  -0.1216394    1.2956094   0.5810063

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 passed to the child process, whereas the evaluated function cannot refer to variables in the parent. For example, the following does not work:

mycars <- cars
r(function() summary(mycars))
 
#> Error in summary(mycars) (from internal.R#90) : object 'mycars' not found

But this does:

r(function(x) summary(x), args = list(mycars))
 
#>     speed           dist
#> Min.   : 4.0   Min.   :  2.00
#> 1st Qu.:12.0   1st Qu.: 26.00
#> Median :15.0   Median : 36.00
#> Mean   :15.4   Mean   : 42.98
#> 3rd Qu.:19.0   3rd Qu.: 56.00
#> Max.   :25.0   Max.   :120.00

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.

r(function() { g <- igraph::sample_gnp(1000, 4/1000); igraph::diameter(g) })
 
#> 12

Error handling

callr provides three ways to handle errors that happen in the child process. The default is to forward any errors to the parent:

r(function() 1 + "A")
#> Error in 1 + "A" : non-numeric argument to binary operator

You can catch these errors on the parent, but the context is of course lost. To get the context, you need to specify the error = "stack" option. This copies the whole stack to the parent on an error. The stack is part of the error object thrown on the parent, and you can catch it with tryCatch, and examine it. Here is an example:

tryCatch(
  r(function() { f <- function() g(); g <- function() 1 + "A"; f() },
    error = "stack"),
  error = function(e) print(e$stack)
)
 
#> $`(function () \n{\n    f <- function() g()\n    g <- function() 1 + "A"\n    f()`
#> <environment: 0x7fc1e4b61e08>
#>
#> $`#2: f()`
#> <environment: 0x7fc1e4b62150>
#>
#> $`#2: g()`
#> <environment: 0x7fc1e4b62188>
#>
#> attr(,"error.message")
#> [1] "non-numeric argument to binary operator"
#> attr(,"class")
#> [1] "dump.frames"

The third possible value for error is "debugger" which starts a debugger (see ?debugger in the call stack returned from the child:

r(function() { f <- function() g(); g <- function() 1 + "A"; f() },
  error = "debugger")
 
#> Message:  non-numeric argument to binary operator
#> Available environments had calls:
#> 1: (function ()
#> {
#>     f <- function() g()
#>     g <- function() 1 + "A"
#>     f()
#> 2: #1: f()
#> 3: #1: g()
#>
#> Enter an environment number, or 0 to exit  Selection:

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 <- r(function() { print("hello world!"); message("hello again!") },
  stdout = "/tmp/out", stderr = "/tmp/err"
)
readLines("/tmp/out")
 
#> [1] "[1] \"hello world!\""
 
readLines("/tmp/err")
 
#> [1] "hello again!"

Showing progress

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.

Tips

  1. It is good practice to create an anonymous function for the r() call, instead of passing a function from a package to r() directly. This is because callr resets the environment of the function, which prevents some functions from working. Here is an example:
r(praise::praise)
 
#> Error: could not find function "is_template"

But with an anonymous function this works fine:

r(function() praise::praise())
 
#> [1] "You are outstanding!"
  1. If the function you call in the other session calls quit() with a non-zero status, then callr interprets that as an R crash. Zero status is a clean exit, but callr returns NULL, as no results were saved:
r(function() quit(status = 0))
#> NULL
 
r(function() quit(status = 2))
#> Error: callr failed, could not start R, exited with non-zero status, has crashed or was killed

R CMD <command>

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:

rcmd("config", "CC")
 
#>$stdout
#>[1] "clang\n"
#>
#>$stderr
#>[1] ""
#>
#>$status
#>[1] 0

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

License

MIT © Mango Solutions, RStudio

News

callr 3.2.0

  • r(), rcmd() and rscript() can now redirect the standard error of the subprocess its standard output. This allows to keep them correctly interleaved. For this, you need to either set the stderr argument to the special string "2>&1", or to the same output file as specified for stdout.

  • r(), rcmd() and rscript() now pass ... arguments to processx::run(). r_bg() and rcmd_bg() pass ... arguments to the processx::process constructor. For r_process, rcmd_process and rscript_process extra arguments can be specified as options$extra, these are also passed to the processx::process constructor (#100).

callr 3.1.1

  • r(), r_bg(), etc. now handle messages from the cliapp package properly. They used to make the R session exit.

  • Better default for the repos option in callr subprocesses. callr no longer creates duplicate "CRAN" entries. By default the new default_repos() function is used to set repos in the subprocess.

callr 3.1.0

  • New rscript() function and rscript_process class to execute R scripts via Rscript (#40, #81).

  • Library paths are now correctly set up for system() (and similar) calls from the callr subprocesses (#83, #84).

  • Pass options("repos") to the child process as is, without checking. Closes #82.

  • r_session$run_with_output() now returns an S3 object with class callr_session_result.

  • r_session$run*() handle interrupts properly. It tries to interrupt the background process fist, kills it if it is not interruptable, and then re-throws the interrupt condition, going back to the top level prompt if the re-thrown condition is un-caught.

callr 3.0.0

  • New r_session class: a background R session you can send commands to (#56).

  • Rewrote passing the library path to the subprocess (#73, #75)

  • Retain names of the repos option (#67, @jennybc)

callr 2.0.4

  • pkgdown web site at https://callr.r-lib.org (#52, #53).

  • callr users .Renviron files now (and R_ENVIRON_USER as well), but overrides the library path, as requested in r(), etc. (#30).

  • callr now handles the case when the subprocess calls quit().

  • callr now uses the processx package, instead of embedded code, to create and control processes.

callr 2.0.3

  • The default behavior on error can be set now with the callr.error option.

  • Better error message if the child R process crashes or gets killed. (#41)

  • r_bg and rcmd_bg now have the supervise option (#45).

callr 2.0.2

callr 2.0.1

  • Fix compilation issues on CRAN's Solaris machine

  • Fix a test failure on CRAN's macOS machine

callr 2.0.0

  • Run R or R CMD * in the background, see r_bg(), rcmd_bg(), and also r_process and rcmd_process

  • The defaults for r() are safer now, the match the defaults of r_safe(). r_safe() is kept for compatibility. r_copycat() has the old r() defaults.

  • The defaults for rcmd() are safer now, the match the defaults of rcmd_safe(). rcmd_safe() is kept for compatibility. rcmd_copycat() has the old rcmd() defaults.

  • Support block callbacks, in addition to line callbacks. Block callbacks are called for arbitrary chunks of output, even without a newline

  • Add spinner argument to show a spinner in r() or rcmd()

  • Support timeouts, via the timeout argument

  • Fix bug when stdout and stderr are redirected to the same file

  • rcmd_safe_env() to allow extending the environment variables set in safe mode

  • rcmd() gets a fail_on_status argument

  • rcmd() gets an echo argument to potentially show the command to be run on the screen (#15)

  • rcmd() gets a wd argument to set the working directory

callr 1.0.0

First public release.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.
install.packages("callr")

3.2.0 by Gábor Csárdi, a month ago

https://github.com/r-lib/callr#readme

Report a bug at https://github.com/r-lib/callr/issues

Browse source code at https://github.com/cran/callr

Authors: Gábor Csárdi [aut, cre, cph] , Winston Chang [aut] , RStudio [cph, fnd] , Mango Solutions [cph, fnd]

Documentation:   PDF Manual  

MIT + file LICENSE license

Imports processx, R6, utils

Suggests cliapp, covr, crayon, pingr, ps, testthat, withr

Imported by Rcrawler, cyclocomp, devtools, document, eplusr, fakemake, future.callr, gitgadget, languageserver, pak, pkgbuild, pkgdown, rcmdcheck, reprex, rhub, shinytest, webdriver, webshot, workflowr.

Suggested by cliapp, dplyr, drake, filelock, httpuv, keyring, liteq, pkgcache, processx, ps, remotes, reticulate, rmarkdown, sessioninfo.

See at CRAN

R links

R homepage

Download R

Mailing lists

R documentation

R manuals

R FAQs

The R Journal

CRAN links

CRAN homepage

CRAN repository policy

Submit a package

METACRAN stuff

About METACRAN

At github

Report a bug