callr v3.2.0
Monthly downloads
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.
Readme
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.
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!"
2) 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
Functions in callr
Name | Description | |
r_vanilla | Run an R child process, with no configuration | |
r_session | External R Session | |
rcmd_safe_env | rcmd_safe_env returns a set of environment variables that are more appropriate for rcmd_safe(). It is exported to allow manipulating these variables (e.g. add an extra one), before passing them to the rcmd() functions. | |
reexports | Objects exported from other packages | |
rcmd | Run an R CMD command | |
rcmd_copycat | Call and R CMD command, while mimicking the current R session | |
rscript_process_options | Create options for an rscript_process object | |
rcmd_bg | Run an R CMD command in the background | |
rcmd_process | External R CMD Process | |
convert_and_check_my_args | Convert and check function arguments | |
rcmd_process_options | Create options for an rcmd_process object | |
r_session_options | Create options for an r_session object | |
rscript | Run an R script | |
rscript_process | External Rscript process | |
r_process | External R Process | |
callr | Call R from R | |
default_repos | Default value for the repos option in callr subprocesses | |
r_bg | Evaluate an expression in another R session, in the background | |
r_process_options | Create options for an r_process object | |
r | Evaluate an expression in another R session | |
make_error | Create an error object | |
get_result | Read the result object from the output file, or the error | |
r_copycat | Run an R process that mimics the current R process | |
No Results! |
Last month downloads
Details
License | MIT + file LICENSE |
LazyData | true |
URL | https://github.com/r-lib/callr#readme |
BugReports | https://github.com/r-lib/callr/issues |
RoxygenNote | 6.1.1 |
Encoding | UTF-8 |
NeedsCompilation | no |
Packaged | 2019-03-15 12:29:40 UTC; gaborcsardi |
Repository | CRAN |
Date/Publication | 2019-03-15 13:04:12 UTC |
suggests | cliapp , covr , crayon , pingr , ps , testthat , withr |
imports | processx (>= 3.3.0) , R6 , utils |
Contributors | RStudio, Winston Chang, Mango Solutions |
Include our badge in your README
[](http://www.rdocumentation.org/packages/callr)