callr version 2.0.0,
r() is equivalent to
tries to set up a less error prone execution environment. In particular:
Ensures that at least one reasonable CRAN mirror is set up.
Adds some command line arguments to avoid saving
Ignores the system and user profiles (by default).
Sets various environment variables:
CYGWINto avoid warnings about DOS-style paths,
R_TESTSto avoid issues when
callris invoked from unit tests,
R_PDFVIEWERto avoid starting a browser or a PDF viewer. See
r( func, args = list(), libpath = .libPaths(), repos = default_repos(), stdout = NULL, stderr = NULL, poll_connection = TRUE, error = getOption("callr.error", "error"), cmdargs = c("--slave", "--no-save", "--no-restore"), show = FALSE, callback = NULL, block_callback = NULL, spinner = show && interactive(), system_profile = FALSE, user_profile = "project", env = rcmd_safe_env(), timeout = Inf, package = FALSE, arch = "same", ... ) r_safe( func, args = list(), libpath = .libPaths(), repos = default_repos(), stdout = NULL, stderr = NULL, poll_connection = TRUE, error = getOption("callr.error", "error"), cmdargs = c("--slave", "--no-save", "--no-restore"), show = FALSE, callback = NULL, block_callback = NULL, spinner = show && interactive(), system_profile = FALSE, user_profile = "project", env = rcmd_safe_env(), timeout = Inf, package = FALSE, arch = "same", ... )
Function object to call in the new R process. The function should be self-contained and only refer to other functions and use variables explicitly from other packages using the
::notation. By default the environment of the function is set to
.GlobalEnvbefore passing it to the child process. (See the
packageoption if you want to keep the environment.) Because of this, it is good practice to create an anonymous function and pass that to
callr, instead of passing a function object from a (base or other) package. In particular
does not work, because
.libPathsis defined in a special environment, but
works just fine.
Arguments to pass to the function. Must be a list.
The library path.
NULL, then no
reposoption is set. This options is only used if
FALSE, as it is set using the system or the user profile.
The name of the file the standard output of the child R process will be written to. If the child process runs with the
--slaveoption (the default), then the commands are not echoed and will not be shown in the standard output. Also note that you need to call
print()explicitly to show the output of the command(s).
The name of the file the standard error of the child R process will be written to. In particular
message()sends output to the standard error. If nothing was sent to the standard error, then this file will be empty. This argument can be the same file as
stdout, in which case they will be correctly interleaved. If this is the string
"2>&1", then standard error is redirected to standard output.
Whether to have a control connection to the process. This is used to transmit messages from the subprocess to the main process.
What to do if the remote process throws an error. See details below.
Command line arguments to pass to the R process. Note that
c("-f", rscript)is appended to this,
rscriptis the name of the script file to run. This contains a call to the supplied function and some error handling code.
Logical, whether to show the standard output on the screen while the child process is running. Note that this is independent of the
stderrarguments. The standard error is not shown currently.
A function to call for each line of the standard output and standard error from the child process. It works together with the
showoption; i.e. if
show = TRUE, and a callback is provided, then the output is shown of the screen, and the callback is also called.
A function to call for each block of the standard output and standard error. This callback is not line oriented, i.e. multiple lines or half a line can be passed to the callback.
Whether to show a calming spinner on the screen while the child R session is running. By default it is shown if
show = TRUEand the R session is interactive.
Whether to use the system profile file.
Whether to use the user's profile file. If this is
"project", then only the profile from the working directory is used, but the
R_PROFILE_USERenvironment variable and the user level profile are not. See also "Security considerations" below.
Environment variables to set for the child process.
Timeout for the function call to finish. It can be a base::difftime object, or a real number, meaning seconds. If the process does not finish before the timeout period expires, then a
system_command_timeout_errorerror is thrown.
Infmeans no timeout.
Whether to keep the environment of
funcwhen passing it to the other package. Possible values are:
FALSE: reset the environment to
.GlobalEnv. This is the default.
TRUE: keep the environment as is.
pkg: set the environment to the
Architecture to use in the child process, for multi-arch builds of R. By default the same as the main process. See
supported_archs(). If it contains a forward or backward slash character, then it is taken as the path to the R executable. Note that on Windows you need the path to
Extra arguments are passed to
r() function from before 2.0.0 is called
callr handles errors properly. If the child process throws an
callr throws an error with the same error message
in the main process.
error expert argument may be used to specify a different
behavior on error. The following values are possible:
erroris the default behavior: throw an error in the main process, with a prefix and the same error message as in the subprocess.
stackalso throws an error in the main process, but the error is of a special kind, class
callr_error, and it contains both the original error object, and the call stack of the child, as written out by
utils::dump.frames(). This is now deprecated, because the error thrown for
"error"has the same information.
debuggeris similar to
stack, but in addition to returning the complete call stack, it also start up a debugger in the child call stack, via
The default error behavior can be also set using the
option. This is useful to debug code that uses
callr uses parent errors, to keep the stacks of the main process and the subprocess(es) in the same error object.
callr makes a copy of the user's
.Renviron file and potentially of
the local or user
.Rprofile, in the session temporary
directory. Avoid storing sensitive information such as passwords, in
your environment file or your profile, otherwise this information will
get scattered in various files, at least temporarily, until the
subprocess finishes. You can use the keyring package to avoid passwords
in plain files.
args are copied to the child process by first serializing them
into a temporary file using
saveRDS() and then loading them back into the
child session using
readRDS(). The same strategy is used to copy the result
func(args) to the main session. Note that some objects, notably
externalptr type, won't work as expected after being
saved to a file and loaded back.
For performance reasons
compress=FALSE is used when serializing with
saveRDS(), this can be disabled by setting
options(callr.compress_transport = TRUE).