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.
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.
Install the stable version from CRAN:
install.packages("callr")
Install the development version from GitHub:
source("https://install-github.me/r-lib/callr")
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
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 <- carsr(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.
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
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:
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!"
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.
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!"
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.
MIT © Mango Solutions, RStudio
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).
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.
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.
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)
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.
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).
Fix a bug with R-devel, caused by the change on 2018-02-08: https://github.com/wch/r-source/commit/924582943706100e88a11d6bb0585d25779c91f5 #37, #38
Fix a race condition on Windows, when creating named pipes for stdout or stderr. The client sometimes didn't wait for the server, and callr failed with ERROR_PIPE_BUSY (231, All pipe instances are busy).
Fix compilation issues on CRAN's Solaris machine
Fix a test failure on CRAN's macOS machine
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
First public release.