callr-package: Call R from R
In callr: Call R from R
callr-package R Documentation
Call R from R
Description
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.
callr
Features
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.
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]))
#> 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 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))
#> Error:
#> ! in callr subprocess.
#> Caused by error in `summary(mycars)`:
#> ! object 'mycars' not found
#> Type .Last.error to see the more details.
But this does:
mycars <- cars
callr::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.
callr::r(function() { g <- igraph::sample_gnp(1000, 4/1000); igraph::diameter(g) })
#> [1] 11
Error handling
callr copies errors from the child process back to the main R session:
callr::r(function() 1 + "A")
#> Error:
#> ! in callr subprocess.
#> Caused by error in `1 + "A"`:
#> ! non-numeric argument to binary operator
#> Type .Last.error to see the more details.
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
#> Error:
#> ! in callr subprocess.
#> Caused by error in `1 + "A"`:
#> ! non-numeric argument to binary operator
#> ---
#> Backtrace:
#> 1. callr::r(function() 1 + "A")
#> 2. callr:::get_result(output = out, options)
#> 3. callr:::throw(callr_remote_error(remerr, output), parent = fix_msg(remerr[[3]
#> ]))
#> ---
#> Subprocess backtrace:
#> 1. base::.handleSimpleError(function (e) …
#> 2. global h(simpleError(msg, call))
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")
#> [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.
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
#> PROCESS 'R', running, pid 58242.
This is a list of all r_process methods:
ls(rp)
#> [1] "as_ps_handle" "clone" "finalize"
#> [4] "format" "get_cmdline" "get_cpu_times"
#> [7] "get_error_connection" "get_error_file" "get_exe"
#> [10] "get_exit_status" "get_input_connection" "get_input_file"
#> [13] "get_memory_info" "get_name" "get_output_connection"
#> [16] "get_output_file" "get_pid" "get_poll_connection"
#> [19] "get_result" "get_start_time" "get_status"
#> [22] "get_username" "get_wd" "has_error_connection"
#> [25] "has_input_connection" "has_output_connection" "has_poll_connection"
#> [28] "initialize" "interrupt" "is_alive"
#> [31] "is_incomplete_error" "is_incomplete_output" "is_supervised"
#> [34] "kill" "kill_tree" "poll_io"
#> [37] "print" "read_all_error" "read_all_error_lines"
#> [40] "read_all_output" "read_all_output_lines" "read_error"
#> [43] "read_error_lines" "read_output" "read_output_lines"
#> [46] "resume" "signal" "supervise"
#> [49] "suspend" "wait" "write_input"
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:
-
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.
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)
#> [[1]]
#> output error process
#> "silent" "silent" "silent"
#>
#> [[2]]
#> output error process
#> "ready" "ready" "ready"
#>
rp2$get_result()
#> [1] "2 done"
processx::poll(list(rp1), 1000)
#> [[1]]
#> output error process
#> "silent" "silent" "ready"
#>
rp1$get_result()
#> [1] "1 done"
Persistent R sessions
r_session is another processx::process subclass that represents a persistent background R session:
rs <- callr::r_session$new()
rs
#> R SESSION, alive, idle, pid 58288.
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))
#> [1] 0.8047354 0.8938617 0.7142338 0.8505395 0.3118376 0.7083882 0.9514367
#> [8] 0.2536755 0.6727270 0.3359578
rs$call(function() rnorm(10))
rs
#> R SESSION, alive, busy, pid 58294.
rs$poll_process(2000)
#> [1] "ready"
rs$read()
#> $code
#> [1] 200
#>
#> $message
#> [1] "done callr-rs-result-e3324ebebc8b"
#>
#> $result
#> [1] -0.60962697 -0.41063130 0.22121432 1.44621900 0.26890394 0.11432756
#> [7] -0.53206118 0.47493933 0.02069551 1.37348004
#>
#> $stdout
#> [1] ""
#>
#> $stderr
#> [1] ""
#>
#> $error
#> NULL
#>
#> attr(,"class")
#> [1] "callr_session_result"
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")
#> $status
#> [1] 0
#>
#> $stdout
#> [1] "clang -arch arm64\n"
#>
#> $stderr
#> [1] ""
#>
#> $timeout
#> [1] FALSE
#>
#> $command
#> [1] "/Library/Frameworks/R.framework/Versions/4.2-arm64/Resources/bin/R"
#> [2] "CMD"
#> [3] "config"
#> [4] "CC"
#>
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
-
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.
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.
Author(s)
Maintainer: Gábor Csárdi csardi.gabor@gmail.com (ORCID) [copyright holder]
Authors:
Winston Chang
Other contributors:
Posit Software, PBC [copyright holder, funder]
Ascent Digital Services [copyright holder, funder]
See Also
Useful links:
callr documentation built on June 22, 2024, 6:48 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| callr-package | R Documentation |
Call R from R
Description
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.
callr
Features
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 CMDcommands, synchronously or asynchronously.Can call R scripts, synchronously or asynchronously.
Provides extensible
r_process,rcmd_processandrscript_processR6 classes, based onprocessx::process.
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]))
#> 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 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))
#> Error: #> ! in callr subprocess. #> Caused by error in `summary(mycars)`: #> ! object 'mycars' not found #> Type .Last.error to see the more details.
But this does:
mycars <- cars callr::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.
callr::r(function() { g <- igraph::sample_gnp(1000, 4/1000); igraph::diameter(g) })
#> [1] 11
Error handling
callr copies errors from the child process back to the main R session:
callr::r(function() 1 + "A")
#> Error: #> ! in callr subprocess. #> Caused by error in `1 + "A"`: #> ! non-numeric argument to binary operator #> Type .Last.error to see the more details.
.Last.error
#> Error: #> ! in callr subprocess. #> Caused by error in `1 + "A"`: #> ! non-numeric argument to binary operator #> --- #> Backtrace: #> 1. callr::r(function() 1 + "A") #> 2. callr:::get_result(output = out, options) #> 3. callr:::throw(callr_remote_error(remerr, output), parent = fix_msg(remerr[[3] #> ])) #> --- #> Subprocess backtrace: #> 1. base::.handleSimpleError(function (e) … #> 2. global h(simpleError(msg, call))
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")
#> [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.
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
#> PROCESS 'R', running, pid 58242.
This is a list of all r_process methods:
ls(rp)
#> [1] "as_ps_handle" "clone" "finalize" #> [4] "format" "get_cmdline" "get_cpu_times" #> [7] "get_error_connection" "get_error_file" "get_exe" #> [10] "get_exit_status" "get_input_connection" "get_input_file" #> [13] "get_memory_info" "get_name" "get_output_connection" #> [16] "get_output_file" "get_pid" "get_poll_connection" #> [19] "get_result" "get_start_time" "get_status" #> [22] "get_username" "get_wd" "has_error_connection" #> [25] "has_input_connection" "has_output_connection" "has_poll_connection" #> [28] "initialize" "interrupt" "is_alive" #> [31] "is_incomplete_error" "is_incomplete_output" "is_supervised" #> [34] "kill" "kill_tree" "poll_io" #> [37] "print" "read_all_error" "read_all_error_lines" #> [40] "read_all_output" "read_all_output_lines" "read_error" #> [43] "read_error_lines" "read_output" "read_output_lines" #> [46] "resume" "signal" "supervise" #> [49] "suspend" "wait" "write_input"
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:
-
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 aCTRL+Ckey 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()andresume()to stop and continue a process. -
wait()to wait for the completion of the process, with a timeout.
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)
#> [[1]] #> output error process #> "silent" "silent" "silent" #> #> [[2]] #> output error process #> "ready" "ready" "ready" #>
rp2$get_result()
#> [1] "2 done"
processx::poll(list(rp1), 1000)
#> [[1]] #> output error process #> "silent" "silent" "ready" #>
rp1$get_result()
#> [1] "1 done"
Persistent R sessions
r_session is another processx::process subclass that represents a persistent background R session:
rs <- callr::r_session$new() rs
#> R SESSION, alive, idle, pid 58288.
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))
#> [1] 0.8047354 0.8938617 0.7142338 0.8505395 0.3118376 0.7083882 0.9514367 #> [8] 0.2536755 0.6727270 0.3359578
rs$call(function() rnorm(10)) rs
#> R SESSION, alive, busy, pid 58294.
rs$poll_process(2000)
#> [1] "ready"
rs$read()
#> $code #> [1] 200 #> #> $message #> [1] "done callr-rs-result-e3324ebebc8b" #> #> $result #> [1] -0.60962697 -0.41063130 0.22121432 1.44621900 0.26890394 0.11432756 #> [7] -0.53206118 0.47493933 0.02069551 1.37348004 #> #> $stdout #> [1] "" #> #> $stderr #> [1] "" #> #> $error #> NULL #> #> attr(,"class") #> [1] "callr_session_result"
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")
#> $status #> [1] 0 #> #> $stdout #> [1] "clang -arch arm64\n" #> #> $stderr #> [1] "" #> #> $timeout #> [1] FALSE #> #> $command #> [1] "/Library/Frameworks/R.framework/Versions/4.2-arm64/Resources/bin/R" #> [2] "CMD" #> [3] "config" #> [4] "CC" #>
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
-
CALLR_NO_TEMP_DLLS: Iftrue, 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 totrue, and then callr will use the DLL file from the installed processx package. See also https://github.com/r-lib/callr/issues/273.
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.
Author(s)
Maintainer: Gábor Csárdi csardi.gabor@gmail.com (ORCID) [copyright holder]
Authors:
Winston Chang
Other contributors:
Posit Software, PBC [copyright holder, funder]
Ascent Digital Services [copyright holder, funder]
See Also
Useful links:
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.