Description

This function allows users ofcallr to specify functions that get invokedwhenever an R session is launched. The function can modify the environmentvariables and command line arguments.

Usage

add_hook(...)

Arguments

Details

The prototype of the hook function is⁠function (options)⁠, and it isexpected to return the modifiedoptions.

Value

add_hook is called for its side-effects.

Description

callr sets therepos option in subprocesses, to make sure thata CRAN mirror is set up. This is because the subprocess cannot bringup the menu of CRAN mirrors for the user to choose from.

Usage

default_repos()

Value

Named character vector, the default value of thereposoption in callr subprocesses.

Examples

default_repos()

Description

Fromcallr version 2.0.0,r() is equivalent tor_safe(), andtries 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.RData files, etc.

• Ignores the system and user profiles (by default).

• Sets various environment variables:CYGWIN to avoidwarnings about DOS-style paths,R_TESTS to avoid issueswhencallr is invoked from unit tests,R_BROWSERandR_PDFVIEWER to avoid starting a browser or a PDF viewer.Seercmd_safe_env().

Usage

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",...)

Arguments

r(.libPaths)

r(function() .libPaths())

Details

Ther() function from before 2.0.0 is calledr_copycat() now.

Value

Value of the evaluated expression.

Error handling

callr handles errors properly. If the child process throws anerror, thencallr throws an error with the same error messagein the main process.

Theerror expert argument may be used to specify a differentbehavior on error. The following values are possible:

• error is the default behavior: throw an error in the main process,with a prefix and the same error message as in the subprocess.

• stack also throws an error in the main process, but the erroris of a special kind, classcallr_error, and it containsboth the original error object, and the call stack of the child,as written out byutils::dump.frames(). This is now deprecated,because the error thrown for"error" has the same information.

• debugger is similar tostack, but in additionto returning the complete call stack, it also start up a debuggerin the child call stack, viautils::debugger().

The default error behavior can be also set using thecallr.erroroption. This is useful to debug code that usescallr.

callr uses parent errors, to keep the stacks of the main process and thesubprocess(es) in the same error object.

Security considerations

callr makes a copy of the user's.Renviron file and potentially ofthe local or user.Rprofile, in the session temporarydirectory. Avoid storing sensitive information such as passwords, inyour environment file or your profile, otherwise this information willget scattered in various files, at least temporarily, until thesubprocess finishes. You can use the keyring package to avoid passwordsin plain files.

Transporting objects

func andargs are copied to the child process by first serializing theminto a temporary file usingsaveRDS() and then loading them back into thechild session usingreadRDS(). The same strategy is used to copy the resultof callingfunc(args) to the main session. Note that some objects, notablythose withexternalptr type, won't work as expected after beingsaved to a file and loaded back.

For performance reasonscompress=FALSE is used when serializing withsaveRDS(), this can be disabled by settingoptions(callr.compress_transport = TRUE).

See Also

Other callr functions:r_copycat(),r_vanilla()

Examples

# Workspace is emptyr(function() ls())# library path is the same by defaultr(function() .libPaths()).libPaths()

Description

Starts evaluating an R function call in a background R process, andreturns immediately.Usep$get_result() to collect the result or to throw an errorif the background computation failed.

Usage

r_bg(  func,  args= list(),  libpath= .libPaths(),  repos= default_repos(),  stdout="|",  stderr="|",  poll_connection=TRUE,  error= getOption("callr.error","error"),  cmdargs= c("--slave","--no-save","--no-restore"),  system_profile=FALSE,  user_profile="project",  env= rcmd_safe_env(),  supervise=FALSE,  package=FALSE,  arch="same",...)

Arguments

r(.libPaths)

r(function() .libPaths())

Value

Anr_process object, which inherits fromprocess,so allprocess methods can be called on it, and in addition it alsohas aget_result() method to collect the result.

Security considerations

callr makes a copy of the user's.Renviron file and potentially ofthe local or user.Rprofile, in the session temporarydirectory. Avoid storing sensitive information such as passwords, inyour environment file or your profile, otherwise this information willget scattered in various files, at least temporarily, until thesubprocess finishes. You can use the keyring package to avoid passwordsin plain files.

Examples

rx<- r_bg(function()1+2)# wait until it is donerx$wait()rx$is_alive()rx$get_result()

Description

Differences tor():

• No extra repositories are set up.

• The--no-save,--no-restorecommand line arguments are not used. (But--slave still is.)

• The system profile and the user profile are loaded.

• No extra environment variables are set up.

Usage

r_copycat(  func,  args= list(),  libpath= .libPaths(),  repos= getOption("repos"),  cmdargs="--slave",  system_profile=TRUE,  user_profile=TRUE,  env= character(),...)

Arguments

r(.libPaths)

r(function() .libPaths())

Security considerations

callr makes a copy of the user's.Renviron file and potentially ofthe local or user.Rprofile, in the session temporarydirectory. Avoid storing sensitive information such as passwords, inyour environment file or your profile, otherwise this information willget scattered in various files, at least temporarily, until thesubprocess finishes. You can use the keyring package to avoid passwordsin plain files.

See Also

Other callr functions:r(),r_vanilla()

Description

An R process that runs in the background. This is an R6 class thatextends theprocessx::process class. The process starts in thebackground, evaluates an R function call, and then quits.

Super class

processx::process ->r_process

Methods

Public methods

• r_process$new()

• r_process$get_result()

• r_process$clone()

Methodnew()

Start a new R process in the background.

Usage

r_process$new(options)

Arguments

Returns

A newr_process object.

Methodget_result()

Return the result, an R object, from a finishedbackground R process. If the process has not finished yet, it throwsan error. (You can usewait() method (seeprocessx::process) towait for the process to finish, optionally with a timeout.) You canalso useprocessx::poll() to wait for the end of the process,together with other processes or events.

Usage

r_process$get_result()

Returns

The return value of the R expression evaluated in the Rprocess.

Methodclone()

The objects of this class are cloneable with this method.

Usage

r_process$clone(deep = FALSE)

Arguments

Examples

## List all options and their default values:r_process_options()## Start an R process in the background, wait for it, get resultopts<- r_process_options(func=function()1+1)rp<- r_process$new(opts)rp$wait()rp$get_result()

Create options for anr_process object

Description

Create options for anr_process object

Usage

r_process_options(...)

Arguments

Value

A list of options.

r_process_options() creates a set of options to initialize a newobject from ther_process class. Its arguments must be named, thenames are used as option names. The options correspond to (some of)the arguments of ther() function. At least thefunc option must bespecified, this is the R function to run in the background.

Examples

## List all options and their default values:r_process_options()

Description

A permanent R session that runs in the background. This is an R6 classthat extends theprocessx::process class.

The process is started at the creation of the object, and then it canbe used to evaluate R function calls, one at a time.

Super class

processx::process ->r_session

Public fields

Methods

Public methods

• r_session$new()

• r_session$run()

• r_session$run_with_output()

• r_session$call()

• r_session$poll_process()

• r_session$get_state()

• r_session$get_running_time()

• r_session$read()

• r_session$close()

• r_session$traceback()

• r_session$debug()

• r_session$attach()

• r_session$print()

• r_session$clone()

Methodnew()

creates a new R background process. It can wait for the process tostart up (wait = TRUE), or return immediately, i.e. beforethe process is actually ready to run. In the latter case you may callthepoll_process() method to make sure it is ready.

Usage

r_session$new(options = r_session_options(), wait = TRUE, wait_timeout = 3000)

Arguments

Returns

Anr_session object.

Methodrun()

Similar tor(), but runs the function in a permanent backgroundR session. It throws an error if the function call generated anerror in the child process.

Usage

r_session$run(func, args = list(), package = FALSE)

Arguments

Returns

The return value of the R expression.

Methodrun_with_output()

Similar to⁠$run()⁠, but returns the standard output and error ofthe child process as well. It does not throw on errors, butreturns a non-NULLerror member in the result list.

Usage

r_session$run_with_output(func, args = list(), package = FALSE)

Arguments

Returns

A list with the following entries.

• result: The value returned byfunc. On error this isNULL.

• stdout: The standard output of the process while evaluating

• stderr: The standard error of the process while evaluatingthefunc call.

• error: On error it contains an error object, that contains theerror thrown in the subprocess. Otherwise it isNULL.

• code,message: These fields are used by call internally andyou can ignore them.

Methodcall()

Starts running a function in the background R session, andreturns immediately. To check if the function is done, call thepoll_process() method.

Usage

r_session$call(func, args = list(), package = FALSE)

Arguments

Methodpoll_process()

Poll the R session with a timeout. If the session has finished thecomputation, it returns with"ready". If the timeoutis reached, it returns with"timeout".

Usage

r_session$poll_process(timeout)

Arguments

Returns

Character string"ready" or"timeout".

Methodget_state()

Return the state of the R session.

Usage

r_session$get_state()

Returns

Possible values:

• "starting": starting up,

• "idle": ready to compute,

• "busy": computing right now,

• "finished": the R process has finished.

Methodget_running_time()

Returns the elapsed time since the R process has started, and theelapsed time since the current computation has started. The latterisNA if there is no active computation.

Usage

r_session$get_running_time()

Returns

Named vector ofPOSIXct objects. The names are"total"and"current".

Methodread()

Reads an event from the child process, if there is one available.Events might signal that the function call has finished, or theycan be progress report events.

This is a low level function that you only need to use if youwant to process events (messages) from the R session manually.

Usage

r_session$read()

Returns

NULL if no events are available. Otherwise a named list,which is also acallr_session_result object. The list always hasacode entry which is the type of the event. See alsor_session$public_fields$status for symbolic names of theevent types.

• 200: (DONE) The computation is done, and the event includesthe result, in the same form as for therun() method.

• 201: (STARTED) An R session that was in 'starting' state isready to go.

• 202: (ATTACH_DONE) Used by theattach() method.

• 301: (MSG) A message from the subprocess. The message is acondition object with classcallr_message. (It typically hasother classes, e.g.cli_message for output from the clipackage.)

• 500: (EXITED) The R session finished cleanly. This meansthat the evaluated expression quit R.

• 501: (CRASHED) The R session crashed or was killed.

• 502: (CLOSED) The R session closed its end of the connectionthat callr uses for communication.

Methodclose()

Terminate the current computation and the R process.The session object will be in"finished" state after this.

Usage

r_session$close(grace = 1000)

Arguments

Methodtraceback()

Thetraceback() method can be used after an error in the Rsubprocess. It is equivalent to thebase::traceback() call, inthe subprocess.

On callr version 3.8.0 and above, you need to set thecallr.traceback option toTRUE (in the main process) to makethe subprocess save the trace on error. This is because savingthe trace can be costly for large objects passed as arguments.

Usage

r_session$traceback()

Returns

The same output as frombase::traceback()

Methoddebug()

Interactive debugger to inspect the dumped frames in the subprocess,after an error. See more atr_session_debug.

On callr version 3.8.0 and above, you need to set thecallr.traceback option toTRUE (in the main process) to makethe subprocess dump frames on error. This is because savingthe frames can be costly for large objects passed as arguments.

Usage

r_session$debug()

Methodattach()

Experimental function that provides a REPL(Read-Eval-Print-Loop) to the subprocess.

Usage

r_session$attach()

Methodprint()

Print method for anr_session.

Usage

r_session$print(...)

Arguments

Methodclone()

The objects of this class are cloneable with this method.

Usage

r_session$clone(deep = FALSE)

Arguments

Examples

rs<- r_session$new()rs$run(function()1+2)rs$call(function() Sys.sleep(1))rs$get_state()rs$poll_process(-1)rs$get_state()rs$read()

Description

Ther_session$debug() method is an interactive debugger to inspectthe stack of the background process after an error.

Details

Note that on callr version 3.8.0 and above, you need to set thecallr.traceback option toTRUE (in the main process) to makethe subprocess dump the frames on error. This is because savingthe frames can be costly for large objects passed as arguments.

⁠$debug()⁠ starts a REPL (Read-Eval-Print-Loop), that evaluates Rexpressions in the subprocess. It is similar tobrowser() anddebugger() and also has some extra commands:

• .help prints a short help message.

• .where prints the complete stack trace of the error. (The same asthe⁠$traceback()⁠ method.

• ⁠.inspect <n>⁠ switches the "focus" to frame⁠<n>⁠. Frame 0 is theglobal environment, so⁠.inspect 0⁠ will switch back to that.

To exit the debugger, press the usual interrupt key, i.e.CTRL+c orESC in some GUIs.

Here is an example session that uses⁠$debug()⁠ (some output is omittedfor brevity):

# ----------------------------------------------------------------------> rs <- r_session$new()> rs$run(function() knitr::knit("no-such-file"))Error in rs_run(self, private, func, args) : callr subprocess failed: cannot open the connection> rs$debug()Debugging in process 87361, press CTRL+C (ESC) to quit. Commands:  .where       -- print stack trace  .inspect <n> -- inspect a frame, 0 resets to .GlobalEnv  .help        -- print this message  <cmd>        -- run <cmd> in frame or .GlobalEnv3: file(con, "r")2: readLines(input2, encoding = "UTF-8", warn = FALSE)1: knitr::knit("no-such-file") at #1RS 87361 > .inspect 1RS 87361 (frame 1) > ls() [1] "encoding"  "envir"     "ext"       "in.file"   "input"     "input.dir" [7] "input2"    "ocode"     "oconc"     "oenvir"    "oopts"     "optc"[13] "optk"      "otangle"   "out.purl"  "output"    "quiet"     "tangle"[19] "text"RS 87361 (frame 1) > input[1] "no-such-file"RS 87361 (frame 1) > file.exists(input)[1] FALSERS 87361 (frame 1) > # <CTRL + C># ----------------------------------------------------------------------

Create options for anr_session object

Description

Create options for anr_session object

Usage

r_session_options(...)

Arguments

Value

Named list of options.

The current options are:

• libpath: Library path for the subprocess. By default the same as thecurrent library path. I.e.not necessarily the library path ofa fresh R session.)

• repos:repos option for the subprocess. By default the currentvalue of the main process.

• stdout: Standard output of the sub-process. This can beNULL ora pipe:"|". If it is a pipe then the output of the subprocess isnot included in the responses, but you need to poll and read itmanually. This is for experts. Note that this option is not usedfor the startup phase that currently always runs withstdout = "|".

• stderr: Similar tostdout, but for the standard error. Likestdout, it is not used for the startup phase, which runs withstderr = "|".

• error: See 'Error handling' inr().

• cmdargs: See the same argument ofr(). (Its default might bedifferent, though.)

• system_profile: See the same argument ofr().

• user_profile: See the same argument ofr().

• env: See the same argument ofr().

• load_hook:NULL, or code (quoted) to run in the sub-processat start up. (I.e. not for every singlerun() call.)

• extra: List of extra arguments to pass toprocessx::process.

Callr_session_options() to see the default values.r_session_options() might contain undocumented entries, you cannotchange these.

Examples

r_session_options()

Description

It tries to mimic a fresh R installation. In particular:

• No library path setting.

• No CRAN(-like) repository is set.

• The system and user profiles are not run.

Usage

r_vanilla(  func,  args= list(),  libpath= character(),  repos= c(CRAN="@CRAN@"),  cmdargs="--slave",  system_profile=FALSE,  user_profile=FALSE,  env= character(),...)

Arguments

r(.libPaths)

r(function() .libPaths())

Security considerations

callr makes a copy of the user's.Renviron file and potentially ofthe local or user.Rprofile, in the session temporarydirectory. Avoid storing sensitive information such as passwords, inyour environment file or your profile, otherwise this information willget scattered in various files, at least temporarily, until thesubprocess finishes. You can use the keyring package to avoid passwordsin plain files.

See Also

Other callr functions:r(),r_copycat()

Examples

# Compare to r()r(function() .libPaths())r_vanilla(function() .libPaths())r(function() getOption("repos"))r_vanilla(function() getOption("repos"))

Description

Run an⁠R CMD⁠ command form within R. This will usually startanother R process, from a shell script.

Usage

rcmd(  cmd,  cmdargs= character(),  libpath= .libPaths(),  repos= default_repos(),  stdout=NULL,  stderr=NULL,  poll_connection=TRUE,  echo=FALSE,  show=FALSE,  callback=NULL,  block_callback=NULL,  spinner= show&& interactive(),  system_profile=FALSE,  user_profile="project",  env= rcmd_safe_env(),  timeout=Inf,  wd=".",  fail_on_status=FALSE,...)rcmd_safe(  cmd,  cmdargs= character(),  libpath= .libPaths(),  repos= default_repos(),  stdout=NULL,  stderr=NULL,  poll_connection=TRUE,  echo=FALSE,  show=FALSE,  callback=NULL,  block_callback=NULL,  spinner= show&& interactive(),  system_profile=FALSE,  user_profile="project",  env= rcmd_safe_env(),  timeout=Inf,  wd=".",  fail_on_status=FALSE,...)

Arguments

Details

Starting fromcallr 2.0.0,rcmd() has safer defaults, the same asthercmd_safe() default values. Usercmd_copycat() for the olddefaults.

Value

A list with the command line⁠$command⁠),standard output (⁠$stdout⁠), standard error (stderr),exit status (⁠$status⁠) of the external⁠R CMD⁠ command, andwhether a timeout was reached (⁠$timeout⁠).

Security considerations

callr makes a copy of the user's.Renviron file and potentially ofthe local or user.Rprofile, in the session temporarydirectory. Avoid storing sensitive information such as passwords, inyour environment file or your profile, otherwise this information willget scattered in various files, at least temporarily, until thesubprocess finishes. You can use the keyring package to avoid passwordsin plain files.

See Also

Other R CMD commands:rcmd_bg(),rcmd_copycat()

Examples

rcmd("config","CC")

Description

The child process is started in the background, and the functionreturn immediately.

Usage

rcmd_bg(  cmd,  cmdargs= character(),  libpath= .libPaths(),  stdout="|",  stderr="|",  poll_connection=TRUE,  repos= default_repos(),  system_profile=FALSE,  user_profile="project",  env= rcmd_safe_env(),  wd=".",  supervise=FALSE,...)

Arguments

Value

It returns aprocess object.

Security considerations

callr makes a copy of the user's.Renviron file and potentially ofthe local or user.Rprofile, in the session temporarydirectory. Avoid storing sensitive information such as passwords, inyour environment file or your profile, otherwise this information willget scattered in various files, at least temporarily, until thesubprocess finishes. You can use the keyring package to avoid passwordsin plain files.

See Also

Other R CMD commands:rcmd(),rcmd_copycat()

Description

This function is similar torcmd(), but it has slightly differentdefaults:

• Therepos options is unchanged.

• No extra environment variables are defined.

Usage

rcmd_copycat(  cmd,  cmdargs= character(),  libpath= .libPaths(),  repos= getOption("repos"),  env= character(),...)

Arguments

Security considerations

callr makes a copy of the user's.Renviron file and potentially ofthe local or user.Rprofile, in the session temporarydirectory. Avoid storing sensitive information such as passwords, inyour environment file or your profile, otherwise this information willget scattered in various files, at least temporarily, until thesubprocess finishes. You can use the keyring package to avoid passwordsin plain files.

See Also

Other R CMD commands:rcmd(),rcmd_bg()

Description

An⁠R CMD *⁠ command that runs in the background. This is an R6 classthat extends theprocessx::process class.

Super class

processx::process ->rcmd_process

Methods

Public methods

• rcmd_process$new()

• rcmd_process$clone()

Methodnew()

Start an⁠R CMD⁠ process.

Usage

rcmd_process$new(options)

Arguments

Returns

A newrcmd_process object.

Methodclone()

The objects of this class are cloneable with this method.

Usage

rcmd_process$clone(deep = FALSE)

Arguments

Examples

options<- rcmd_process_options(cmd="config", cmdargs="CC")rp<- rcmd_process$new(options)rp$wait()rp$read_output_lines()

Create options for anrcmd_process object

Description

Create options for anrcmd_process object

Usage

rcmd_process_options(...)

Arguments

Value

A list of options.

rcmd_process_options() creates a set of options to initialize a newobject from thercmd_process class. Its arguments must be named, thenames are used as option names. The options correspond to (some of)the arguments of thercmd() function. At least thecmd option mustbe specified, to select the⁠R CMD⁠ subcommand to run. Typicallycmdargs is specified as well, to supply more arguments to⁠R CMD⁠.

Examples

## List all options and their default values:rcmd_process_options()

rcmd_safe_env returns a set of environment variables that aremore appropriate forrcmd_safe(). It is exported to allow manipulatingthese variables (e.g. add an extra one), before passing them to thercmd() functions.

Description

It currently has the following variables:

• CYGWIN="nodosfilewarning": On Windows, do not warn about MS-DOSstyle file names.

• R_TESTS="" This variable is set by⁠R CMD check⁠, and makes thechild R process load a startup file at startup, from the currentworking directory, that is assumed to be the⁠/test⁠ directoryof the package being checked. If the current working directory ischanged to something else (as it typically is bytestthat, then Rcannot start. Setting it to the empty string ensures thatcallr canbe used from unit tests.

• R_BROWSER="false": typically we don't want to start up a browserfrom the child R process.

• R_PDFVIEWER="false": similarly for the PDF viewer.

Usage

rcmd_safe_env()

Details

Note thatcallr also sets theR_ENVIRON,R_ENVIRON_USER,R_PROFILE andR_PROFILE_USER environment variablesappropriately, unless these are set by the user in theenv argumentof ther, etc. calls.

Value

A named character vector of environment variables.

Description

It uses theRscript program corresponding to the current R version,to run the script. It streamsstdout andstderr of the process.

Usage

rscript(  script,  cmdargs= character(),  libpath= .libPaths(),  repos= default_repos(),  stdout=NULL,  stderr=NULL,  poll_connection=TRUE,  echo=FALSE,  show=TRUE,  callback=NULL,  block_callback=NULL,  spinner=FALSE,  system_profile=FALSE,  user_profile="project",  env= rcmd_safe_env(),  timeout=Inf,  wd=".",  fail_on_status=TRUE,  color=TRUE,...)

Arguments

Security considerations

callr makes a copy of the user's.Renviron file and potentially ofthe local or user.Rprofile, in the session temporarydirectory. Avoid storing sensitive information such as passwords, inyour environment file or your profile, otherwise this information willget scattered in various files, at least temporarily, until thesubprocess finishes. You can use the keyring package to avoid passwordsin plain files.

Description

An⁠Rscript script.R⁠ command that runs in the background. This is anR6 class that extends theprocessx::process class.

Super class

processx::process ->rscript_process

Methods

Public methods

• rscript_process$new()

• rscript_process$clone()

Methodnew()

Create a newRscript process.

Usage

rscript_process$new(options)

Arguments

Methodclone()

The objects of this class are cloneable with this method.

Usage

rscript_process$clone(deep = FALSE)

Arguments

Examples

options<- rscript_process_options(script="script.R")rp<- rscript_process$new(options)rp$wait()rp$read_output_lines()

Create options for anrscript_process object

Description

Create options for anrscript_process object

Usage

rscript_process_options(...)

Arguments

Value

A list of options.

rscript_process_options() creates a set of options to initialize a newobject from therscript_process class. Its arguments must be named,the names are used as option names. The options correspond to (some of)the arguments of therscript() function. At least thescript optionmust be specified, the script file to run.

Examples

## List all options and their default values:rscript_process_options()

Description

This function uses a heuristic, which might fail, so its resultshould be taken as a best guess.

Usage

supported_archs()

Value

Character vector of supported architectures. If thecurrent R build is not a multi-architecture build, then an emptystring scalar is returned.

Examples

supported_archs()