EVOLUTION-MANAGER
Edit File: r_bg.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Evaluate an expression in another R session, in the...</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for r_bg {callr}"><tr><td>r_bg {callr}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Evaluate an expression in another R session, in the background</h2> <h3>Description</h3> <p>Starts evaluating an R function call in a background R process, and returns immediately. </p> <h3>Usage</h3> <pre> 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", ... ) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>func</code></td> <td> <p>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 <code>::</code> notation. By default the environment of the function is set to <code>.GlobalEnv</code> before passing it to the child process. (See the <code>package</code> option if you want to keep the environment.) Because of this, it is good practice to create an anonymous function and pass that to <code>callr</code>, instead of passing a function object from a (base or other) package. In particular </p> <div class="sourceCode"><pre>r(.libPaths) </pre></div> <p>does not work, because <code>.libPaths</code> is defined in a special environment, but </p> <div class="sourceCode"><pre>r(function() .libPaths()) </pre></div> <p>works just fine.</p> </td></tr> <tr valign="top"><td><code>args</code></td> <td> <p>Arguments to pass to the function. Must be a list.</p> </td></tr> <tr valign="top"><td><code>libpath</code></td> <td> <p>The library path.</p> </td></tr> <tr valign="top"><td><code>repos</code></td> <td> <p>The <code>repos</code> option. If <code>NULL</code>, then no <code>repos</code> option is set. This options is only used if <code>user_profile</code> or <code>system_profile</code> is set <code>FALSE</code>, as it is set using the system or the user profile.</p> </td></tr> <tr valign="top"><td><code>stdout</code></td> <td> <p>The name of the file the standard output of the child R process will be written to. If the child process runs with the <code>--slave</code> option (the default), then the commands are not echoed and will not be shown in the standard output. Also note that you need to call <code>print()</code> explicitly to show the output of the command(s).</p> </td></tr> <tr valign="top"><td><code>stderr</code></td> <td> <p>The name of the file the standard error of the child R process will be written to. In particular <code>message()</code> 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 <code>stdout</code>, in which case they will be correctly interleaved. If this is the string <code>"2>&1"</code>, then standard error is redirected to standard output.</p> </td></tr> <tr valign="top"><td><code>poll_connection</code></td> <td> <p>Whether to have a control connection to the process. This is used to transmit messages from the subprocess to the main process.</p> </td></tr> <tr valign="top"><td><code>error</code></td> <td> <p>What to do if the remote process throws an error. See details below.</p> </td></tr> <tr valign="top"><td><code>cmdargs</code></td> <td> <p>Command line arguments to pass to the R process. Note that <code>c("-f", rscript)</code> is appended to this, <code>rscript</code> is the name of the script file to run. This contains a call to the supplied function and some error handling code.</p> </td></tr> <tr valign="top"><td><code>system_profile</code></td> <td> <p>Whether to use the system profile file.</p> </td></tr> <tr valign="top"><td><code>user_profile</code></td> <td> <p>Whether to use the user's profile file. If this is <code>"project"</code>, then only the profile from the working directory is used, but the <code>R_PROFILE_USER</code> environment variable and the user level profile are not. See also "Security considerations" below.</p> </td></tr> <tr valign="top"><td><code>env</code></td> <td> <p>Environment variables to set for the child process.</p> </td></tr> <tr valign="top"><td><code>supervise</code></td> <td> <p>Whether to register the process with a supervisor. If <code>TRUE</code>, the supervisor will ensure that the process is killed when the R process exits.</p> </td></tr> <tr valign="top"><td><code>package</code></td> <td> <p>Whether to keep the environment of <code>func</code> when passing it to the other package. Possible values are: </p> <ul> <li> <p><code>FALSE</code>: reset the environment to <code>.GlobalEnv</code>. This is the default. </p> </li> <li> <p><code>TRUE</code>: keep the environment as is. </p> </li> <li> <p><code>pkg</code>: set the environment to the <code>pkg</code> package namespace. </p> </li></ul> </td></tr> <tr valign="top"><td><code>arch</code></td> <td> <p>Architecture to use in the child process, for multi-arch builds of R. By default the same as the main process. See <code><a href="supported_archs.html">supported_archs()</a></code>. 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 <code>Rterm.exe</code>.</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>Extra arguments are passed to the <a href="../../processx/html/process.html">processx::process</a> constructor.</p> </td></tr> </table> <h3>Value</h3> <p>An <code>r_process</code> object, which inherits from <a href="reexports.html">process</a>, so all <code>process</code> methods can be called on it, and in addition it also has a <code>get_result()</code> method to collect the result. </p> <h3>Security considerations</h3> <p><code>callr</code> makes a copy of the user's <code>.Renviron</code> file and potentially of the local or user <code>.Rprofile</code>, 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. </p> <h3>Examples</h3> <pre> rx <- r_bg(function() 1 + 2) # wait until it is done rx$wait() rx$is_alive() rx$get_result() </pre> <hr /><div style="text-align: center;">[Package <em>callr</em> version 3.7.2 <a href="00Index.html">Index</a>]</div> </body></html>