EVOLUTION-MANAGER
Edit File: r_session.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: External R Session</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_session {callr}"><tr><td>r_session {callr}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>External R Session</h2> <h3>Description</h3> <p>A permanent R session that runs in the background. This is an R6 class that extends the <a href="../../processx/html/process.html">processx::process</a> class. </p> <p>The process is started at the creation of the object, and then it can be used to evaluate R function calls, one at a time. </p> <h3>Super class</h3> <p><code><a href="../../processx/html/process.html">processx::process</a></code> -> <code>r_session</code> </p> <h3>Public fields</h3> <div class="r6-fields"> <dl> <dt><code>status</code></dt><dd><p>Status codes returned by <code>read()</code>.</p> </dd> </dl> </div> <h3>Methods</h3> <h4>Public methods</h4> <ul> <li> <p><a href="#method-r_session-new"><code>r_session$new()</code></a> </p> </li> <li> <p><a href="#method-r_session-run"><code>r_session$run()</code></a> </p> </li> <li> <p><a href="#method-r_session-run_with_output"><code>r_session$run_with_output()</code></a> </p> </li> <li> <p><a href="#method-r_session-call"><code>r_session$call()</code></a> </p> </li> <li> <p><a href="#method-r_session-poll_process"><code>r_session$poll_process()</code></a> </p> </li> <li> <p><a href="#method-r_session-get_state"><code>r_session$get_state()</code></a> </p> </li> <li> <p><a href="#method-r_session-get_running_time"><code>r_session$get_running_time()</code></a> </p> </li> <li> <p><a href="#method-r_session-read"><code>r_session$read()</code></a> </p> </li> <li> <p><a href="#method-r_session-close"><code>r_session$close()</code></a> </p> </li> <li> <p><a href="#method-r_session-traceback"><code>r_session$traceback()</code></a> </p> </li> <li> <p><a href="#method-r_session-debug"><code>r_session$debug()</code></a> </p> </li> <li> <p><a href="#method-r_session-attach"><code>r_session$attach()</code></a> </p> </li> <li> <p><a href="#method-r_session-finalize"><code>r_session$finalize()</code></a> </p> </li> <li> <p><a href="#method-r_session-print"><code>r_session$print()</code></a> </p> </li> <li> <p><a href="#method-r_session-clone"><code>r_session$clone()</code></a> </p> </li></ul> <details><summary>Inherited methods</summary> <ul> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="as_ps_handle"><a href='../../processx/html/process.html#method-process-as_ps_handle'><code>processx::process$as_ps_handle()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="format"><a href='../../processx/html/process.html#method-process-format'><code>processx::process$format()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_cmdline"><a href='../../processx/html/process.html#method-process-get_cmdline'><code>processx::process$get_cmdline()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_cpu_times"><a href='../../processx/html/process.html#method-process-get_cpu_times'><code>processx::process$get_cpu_times()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_error_connection"><a href='../../processx/html/process.html#method-process-get_error_connection'><code>processx::process$get_error_connection()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_error_file"><a href='../../processx/html/process.html#method-process-get_error_file'><code>processx::process$get_error_file()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_exe"><a href='../../processx/html/process.html#method-process-get_exe'><code>processx::process$get_exe()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_exit_status"><a href='../../processx/html/process.html#method-process-get_exit_status'><code>processx::process$get_exit_status()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_input_connection"><a href='../../processx/html/process.html#method-process-get_input_connection'><code>processx::process$get_input_connection()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_input_file"><a href='../../processx/html/process.html#method-process-get_input_file'><code>processx::process$get_input_file()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_memory_info"><a href='../../processx/html/process.html#method-process-get_memory_info'><code>processx::process$get_memory_info()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_name"><a href='../../processx/html/process.html#method-process-get_name'><code>processx::process$get_name()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_output_connection"><a href='../../processx/html/process.html#method-process-get_output_connection'><code>processx::process$get_output_connection()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_output_file"><a href='../../processx/html/process.html#method-process-get_output_file'><code>processx::process$get_output_file()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_pid"><a href='../../processx/html/process.html#method-process-get_pid'><code>processx::process$get_pid()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_poll_connection"><a href='../../processx/html/process.html#method-process-get_poll_connection'><code>processx::process$get_poll_connection()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_result"><a href='../../processx/html/process.html#method-process-get_result'><code>processx::process$get_result()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_start_time"><a href='../../processx/html/process.html#method-process-get_start_time'><code>processx::process$get_start_time()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_status"><a href='../../processx/html/process.html#method-process-get_status'><code>processx::process$get_status()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_username"><a href='../../processx/html/process.html#method-process-get_username'><code>processx::process$get_username()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="get_wd"><a href='../../processx/html/process.html#method-process-get_wd'><code>processx::process$get_wd()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="has_error_connection"><a href='../../processx/html/process.html#method-process-has_error_connection'><code>processx::process$has_error_connection()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="has_input_connection"><a href='../../processx/html/process.html#method-process-has_input_connection'><code>processx::process$has_input_connection()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="has_output_connection"><a href='../../processx/html/process.html#method-process-has_output_connection'><code>processx::process$has_output_connection()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="has_poll_connection"><a href='../../processx/html/process.html#method-process-has_poll_connection'><code>processx::process$has_poll_connection()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="interrupt"><a href='../../processx/html/process.html#method-process-interrupt'><code>processx::process$interrupt()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="is_alive"><a href='../../processx/html/process.html#method-process-is_alive'><code>processx::process$is_alive()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="is_incomplete_error"><a href='../../processx/html/process.html#method-process-is_incomplete_error'><code>processx::process$is_incomplete_error()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="is_incomplete_output"><a href='../../processx/html/process.html#method-process-is_incomplete_output'><code>processx::process$is_incomplete_output()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="is_supervised"><a href='../../processx/html/process.html#method-process-is_supervised'><code>processx::process$is_supervised()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="kill"><a href='../../processx/html/process.html#method-process-kill'><code>processx::process$kill()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="kill_tree"><a href='../../processx/html/process.html#method-process-kill_tree'><code>processx::process$kill_tree()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="poll_io"><a href='../../processx/html/process.html#method-process-poll_io'><code>processx::process$poll_io()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="read_all_error"><a href='../../processx/html/process.html#method-process-read_all_error'><code>processx::process$read_all_error()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="read_all_error_lines"><a href='../../processx/html/process.html#method-process-read_all_error_lines'><code>processx::process$read_all_error_lines()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="read_all_output"><a href='../../processx/html/process.html#method-process-read_all_output'><code>processx::process$read_all_output()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="read_all_output_lines"><a href='../../processx/html/process.html#method-process-read_all_output_lines'><code>processx::process$read_all_output_lines()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="read_error"><a href='../../processx/html/process.html#method-process-read_error'><code>processx::process$read_error()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="read_error_lines"><a href='../../processx/html/process.html#method-process-read_error_lines'><code>processx::process$read_error_lines()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="read_output"><a href='../../processx/html/process.html#method-process-read_output'><code>processx::process$read_output()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="read_output_lines"><a href='../../processx/html/process.html#method-process-read_output_lines'><code>processx::process$read_output_lines()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="resume"><a href='../../processx/html/process.html#method-process-resume'><code>processx::process$resume()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="signal"><a href='../../processx/html/process.html#method-process-signal'><code>processx::process$signal()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="supervise"><a href='../../processx/html/process.html#method-process-supervise'><code>processx::process$supervise()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="suspend"><a href='../../processx/html/process.html#method-process-suspend'><code>processx::process$suspend()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="wait"><a href='../../processx/html/process.html#method-process-wait'><code>processx::process$wait()</code></a></span></li> <li><span class="pkg-link" data-pkg="processx" data-topic="process" data-id="write_input"><a href='../../processx/html/process.html#method-process-write_input'><code>processx::process$write_input()</code></a></span></li> </ul> </details> <hr> <a id="method-r_session-new"></a> <h4>Method <code>new()</code></h4> <p>creates a new R background process. It can wait for the process to start up (<code>wait = TRUE</code>), or return immediately, i.e. before the process is actually ready to run. In the latter case you may call the <code>poll_process()</code> method to make sure it is ready. </p> <h5>Usage</h5> <div class="r"><pre>r_session$new(options = r_session_options(), wait = TRUE, wait_timeout = 3000)</pre></div> <h5>Arguments</h5> <div class="arguments"> <dl> <dt><code>options</code></dt><dd><p>A list of options created via <code><a href="r_session_options.html">r_session_options()</a></code>.</p> </dd> <dt><code>wait</code></dt><dd><p>Whether to wait for the R process to start and be ready for running commands.</p> </dd> <dt><code>wait_timeout</code></dt><dd><p>Timeout for waiting for the R process to start, in milliseconds.</p> </dd> </dl> </div> <h5>Returns</h5> <p>An <code>r_session</code> object. </p> <hr> <a id="method-r_session-run"></a> <h4>Method <code>run()</code></h4> <p>Similar to <code><a href="r.html">r()</a></code>, but runs the function in a permanent background R session. It throws an error if the function call generated an error in the child process. </p> <h5>Usage</h5> <div class="r"><pre>r_session$run(func, args = list(), package = FALSE)</pre></div> <h5>Arguments</h5> <div class="arguments"> <dl> <dt><code>func</code></dt><dd><p>Function object to call in the background R process. Please read the notes for the similar argument of <code><a href="r.html">r()</a></code>.</p> </dd> <dt><code>args</code></dt><dd><p>Arguments to pass to the function. Must be a list.</p> </dd> <dt><code>package</code></dt><dd><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> </dd> </dl> </div> <h5>Returns</h5> <p>The return value of the R expression. </p> <hr> <a id="method-r_session-run_with_output"></a> <h4>Method <code>run_with_output()</code></h4> <p>Similar to <code style="white-space: pre;">$run()</code>, but returns the standard output and error of the child process as well. It does not throw on errors, but returns a non-<code>NULL</code> <code>error</code> member in the result list. </p> <h5>Usage</h5> <div class="r"><pre>r_session$run_with_output(func, args = list(), package = FALSE)</pre></div> <h5>Arguments</h5> <div class="arguments"> <dl> <dt><code>func</code></dt><dd><p>Function object to call in the background R process. Please read the notes for the similar argument of <code><a href="r.html">r()</a></code>.</p> </dd> <dt><code>args</code></dt><dd><p>Arguments to pass to the function. Must be a list.</p> </dd> <dt><code>package</code></dt><dd><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> </dd> </dl> </div> <h5>Returns</h5> <p>A list with the following entries. </p> <ul> <li> <p><code>result</code>: The value returned by <code>func</code>. On error this is <code>NULL</code>. </p> </li> <li> <p><code>stdout</code>: The standard output of the process while evaluating </p> </li> <li> <p><code>stderr</code>: The standard error of the process while evaluating the <code>func</code> call. </p> </li> <li> <p><code>error</code>: On error it contains an error object, that contains the error thrown in the subprocess. Otherwise it is <code>NULL</code>. </p> </li> <li> <p><code>code</code>, <code>message</code>: These fields are used by call internally and you can ignore them. </p> </li></ul> <hr> <a id="method-r_session-call"></a> <h4>Method <code>call()</code></h4> <p>Starts running a function in the background R session, and returns immediately. To check if the function is done, call the <code>poll_process()</code> method. </p> <h5>Usage</h5> <div class="r"><pre>r_session$call(func, args = list(), package = FALSE)</pre></div> <h5>Arguments</h5> <div class="arguments"> <dl> <dt><code>func</code></dt><dd><p>Function object to call in the background R process. Please read the notes for the similar argument of <code><a href="r.html">r()</a></code>.</p> </dd> <dt><code>args</code></dt><dd><p>Arguments to pass to the function. Must be a list.</p> </dd> <dt><code>package</code></dt><dd><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> </dd> </dl> </div> <hr> <a id="method-r_session-poll_process"></a> <h4>Method <code>poll_process()</code></h4> <p>Poll the R session with a timeout. If the session has finished the computation, it returns with <code>"ready"</code>. If the timeout is reached, it returns with <code>"timeout"</code>. </p> <h5>Usage</h5> <div class="r"><pre>r_session$poll_process(timeout)</pre></div> <h5>Arguments</h5> <div class="arguments"> <dl> <dt><code>timeout</code></dt><dd><p>Timeout period in milliseconds.</p> </dd> </dl> </div> <h5>Returns</h5> <p>Character string <code>"ready"</code> or <code>"timeout"</code>. </p> <hr> <a id="method-r_session-get_state"></a> <h4>Method <code>get_state()</code></h4> <p>Return the state of the R session. </p> <h5>Usage</h5> <div class="r"><pre>r_session$get_state()</pre></div> <h5>Returns</h5> <p>Possible values: </p> <ul> <li> <p><code>"starting"</code>: starting up, </p> </li> <li> <p><code>"idle"</code>: ready to compute, </p> </li> <li> <p><code>"busy"</code>: computing right now, </p> </li> <li> <p><code>"finished"</code>: the R process has finished. </p> </li></ul> <hr> <a id="method-r_session-get_running_time"></a> <h4>Method <code>get_running_time()</code></h4> <p>Returns the elapsed time since the R process has started, and the elapsed time since the current computation has started. The latter is <code>NA</code> if there is no active computation. </p> <h5>Usage</h5> <div class="r"><pre>r_session$get_running_time()</pre></div> <h5>Returns</h5> <p>Named vector of <code>POSIXct</code> objects. The names are <code>"total"</code> and <code>"current"</code>. </p> <hr> <a id="method-r_session-read"></a> <h4>Method <code>read()</code></h4> <p>Reads an event from the child process, if there is one available. Events might signal that the function call has finished, or they can be progress report events. </p> <p>This is a low level function that you only need to use if you want to process events (messages) from the R session manually. </p> <h5>Usage</h5> <div class="r"><pre>r_session$read()</pre></div> <h5>Returns</h5> <p><code>NULL</code> if no events are available. Otherwise a named list, which is also a <code>callr_session_result</code> object. The list always has a <code>code</code> entry which is the type of the event. See also <code>r_session$public_fields$status</code> for symbolic names of the event types. </p> <ul> <li> <p><code>200</code>: (<code>DONE</code>) The computation is done, and the event includes the result, in the same form as for the <code>run()</code> method. </p> </li> <li> <p><code>201</code>: (<code>STARTED</code>) An R session that was in 'starting' state is ready to go. </p> </li> <li> <p><code>202</code>: (<code>ATTACH_DONE</code>) Used by the <code>attach()</code> method. </p> </li> <li> <p><code>301</code>: (<code>MSG</code>) A message from the subprocess. The message is a condition object with class <code>callr_message</code>. (It typically has other classes, e.g. <code>cli_message</code> for output from the cli package.) </p> </li> <li> <p><code>500</code>: (<code>EXITED</code>) The R session finished cleanly. This means that the evaluated expression quit R. </p> </li> <li> <p><code>501</code>: (<code>CRASHED</code>) The R session crashed or was killed. </p> </li> <li> <p><code>502</code>: (<code>CLOSED</code>) The R session closed its end of the connection that callr uses for communication. </p> </li></ul> <hr> <a id="method-r_session-close"></a> <h4>Method <code>close()</code></h4> <p>Terminate the current computation and the R process. The session object will be in <code>"finished"</code> state after this. </p> <h5>Usage</h5> <div class="r"><pre>r_session$close(grace = 1000)</pre></div> <h5>Arguments</h5> <div class="arguments"> <dl> <dt><code>grace</code></dt><dd><p>Grace period in milliseconds, to wait for the subprocess to exit cleanly, after its standard input is closed. If the process is still running after this period, it will be killed.</p> </dd> </dl> </div> <hr> <a id="method-r_session-traceback"></a> <h4>Method <code>traceback()</code></h4> <p>The <code>traceback()</code> method can be used after an error in the R subprocess. It is equivalent to the <code><a href="../../base/html/traceback.html">base::traceback()</a></code> call, in the subprocess. </p> <p>On callr version 3.8.0 and above, you need to set the <code>callr.traceback</code> option to <code>TRUE</code> (in the main process) to make the subprocess save the trace on error. This is because saving the trace can be costly for large objects passed as arguments. </p> <h5>Usage</h5> <div class="r"><pre>r_session$traceback()</pre></div> <h5>Returns</h5> <p>The same output as from <code><a href="../../base/html/traceback.html">base::traceback()</a></code> </p> <hr> <a id="method-r_session-debug"></a> <h4>Method <code>debug()</code></h4> <p>Interactive debugger to inspect the dumped frames in the subprocess, after an error. See more at <a href="r_session_debug.html">r_session_debug</a>. </p> <p>On callr version 3.8.0 and above, you need to set the <code>callr.traceback</code> option to <code>TRUE</code> (in the main process) to make the subprocess dump frames on error. This is because saving the frames can be costly for large objects passed as arguments. </p> <h5>Usage</h5> <div class="r"><pre>r_session$debug()</pre></div> <hr> <a id="method-r_session-attach"></a> <h4>Method <code>attach()</code></h4> <p>Experimental function that provides a REPL (Read-Eval-Print-Loop) to the subprocess. </p> <h5>Usage</h5> <div class="r"><pre>r_session$attach()</pre></div> <hr> <a id="method-r_session-finalize"></a> <h4>Method <code>finalize()</code></h4> <p>Finalizer that is called when garbage collecting an <code>r_session</code> object, to clean up temporary files. </p> <h5>Usage</h5> <div class="r"><pre>r_session$finalize()</pre></div> <hr> <a id="method-r_session-print"></a> <h4>Method <code>print()</code></h4> <p>Print method for an <code>r_session</code>. </p> <h5>Usage</h5> <div class="r"><pre>r_session$print(...)</pre></div> <h5>Arguments</h5> <div class="arguments"> <dl> <dt><code>...</code></dt><dd><p>Arguments are not used currently.</p> </dd> </dl> </div> <hr> <a id="method-r_session-clone"></a> <h4>Method <code>clone()</code></h4> <p>The objects of this class are cloneable with this method. </p> <h5>Usage</h5> <div class="r"><pre>r_session$clone(deep = FALSE)</pre></div> <h5>Arguments</h5> <div class="arguments"> <dl> <dt><code>deep</code></dt><dd><p>Whether to make a deep clone.</p> </dd> </dl> </div> <h3>Examples</h3> <pre> rs <- r_ression$new() rs$run(function() 1 + 2) rs$call(function() Sys.sleep(1)) rs$get_state() rs$poll_process(-1) rs$get_state() rs$read() </pre> <hr /><div style="text-align: center;">[Package <em>callr</em> version 3.7.2 <a href="00Index.html">Index</a>]</div> </body></html>