Managing external processes from R is not trivial, and this
class aims to help with this deficiency. It is essentially a small
wrapper around the system
base R function, to return the process
id of the started process, and set its standard output and error
streams. The process id is then used to manage the process.
p <- process$new(command = NULL, args, stdout = NULL, stderr = NULL, cleanup = TRUE, echo_cmd = FALSE, supervise = FALSE, windows_verbatim_args = FALSE, windows_hide_window = FALSE, encoding = "")p$is_alive() p$signal(signal) p$kill(grace = 0.1) p$wait(timeout = -1) p$get_pid() p$get_exit_status() p$restart() p$get_start_time()
p$read_output(n = -1) p$read_error(n = -1) p$read_output_lines(n = -1) p$read_error_lines(n = -1) p$get_output_connection() p$get_error_connection() p$is_incomplete_output() p$is_incomplete_error() p$read_all_output() p$read_all_error() p$read_all_output_lines() p$read_all_error_lines()
p$poll_io(timeout)
print(p)
p
: process
object.
command
: Character scalar, the command to run.
Note that this argument is not passed to a shell, so no
tilde-expansion or variable substitution is performed on it.
It should not be quoted with base::shQuote()
. See
base::normalizePath()
for tilde-expansion.
args
: Character vector, arguments to the command. They will be
used as is, without a shell. They don't need to be escaped.
stdout
: What to do with the standard output. Possible values:
NULL
: discard it; a string, redirect it to this file;
"|"
: create a connection for it.
stderr
: What to do with the standard error. Possible values:
NULL
: discard it; a string, redirect it to this file;
"|"
: create a connection for it.
cleanup
: Whether to kill the process (and its children)
if the process
object is garbage collected.
echo_cmd
: Whether to print the command to the screen before
running it.
supervise
: Whether to register the process with a supervisor.
If TRUE
, the supervisor will ensure that the process is
killed when the R process exits.
windows_verbatim_args
: Whether to omit quoting the arguments
on Windows. It is ignored on other platforms.
windows_hide_window
: Whether to hide the application's window
on Windows. It is ignored on other platforms.
signal
: An integer scalar, the id of the signal to send to
the process. See tools::pskill()
for the list of signals.
grace
: Currently not used.
timeout
: Timeout in milliseconds, for the wait or the I/O
polling.
n
: Number of characters or lines to read.
encoding
: The encoding to assume for stdout
and
stderr
. By default the encoding of the current locale is
used. Note that callr
always reencodes the output of
both streams in UTF-8 currently. If you want to read them
without any conversion, on all platforms, specify "UTF-8"
as
encoding.
The poll_io()
function polls the standard output and standard
error connections of a process, with a timeout. If there is output
in either of them, or they are closed (e.g. because the process exits)
poll_io()
returns immediately.
In addition to polling a single process, the poll()
function
can poll the output of several processes, and returns as soon as any
of them has generated output (or exited).
$new()
starts a new process in the background, and then returns
immediately.
$is_alive()
checks if the process is alive. Returns a logical
scalar.
$signal()
sends a signal to the process. On Windows only the
SIGINT
, SIGTERM
and SIGKILL
signals are interpreted,
and the special 0 signal, The first three all kill the process. The 0
signal return TRUE
if the process is alive, and FALSE
otherwise. On Unix all signals are supported that the OS supports, and
the 0 signal as well.
$kill()
kills the process. It also kills all of its child
processes, except if they have created a new process group (on Unix),
or job object (on Windows). It returns TRUE
if the process
was killed, and FALSE
if it was no killed (because it was
already finished/dead when callr
tried to kill it).
$wait()
waits until the process finishes, or a timeout happens.
Note that if the process never finishes, and the timeout is infinite
(the default), then R will never regain control. It returns
the process itself, invisibly.
$get_pid()
returns the process id of the process.
$get_exit_status
returns the exit code of the process if it has
finished and NULL
otherwise.
$restart()
restarts a process. It returns the process itself.
$get_start_time()
returns the time when the process was
started.
$is_supervised()
returns whether the process is being tracked by
supervisor process.
$supervise()
if passed TRUE
, tells the supervisor to start
tracking the process. If FALSE
, tells the supervisor to stop
tracking the process. Note that even if the supervisor is disabled for a
process, if it was started with cleanup=TRUE
, the process will
still be killed when the object is garbage collected.
$read_output()
reads from the standard output connection of the
process. If the standard output connection was not requested, then
then it returns an error. It uses a non-blocking text connection. This
will work only if stdout="|"
was used. Otherwise, it will throw an
error.
$read_error()
is similar to $read_output
, but it reads
from the standard error stream.
$read_output_lines()
reads lines from standard output connection
of the process. If the standard output connection was not requested, then
then it returns an error. It uses a non-blocking text connection. This
will work only if stdout="|"
was used. Otherwise, it will throw an
error.
$read_error_lines()
is similar to $read_output_lines
, but
it reads from the standard error stream.
$has_output_connection()
returns TRUE
if there is a connection
object for standard output; in other words, if stdout="|"
. It returns
FALSE
otherwise.
$has_error_connection()
returns TRUE
if there is a connection
object for standard error; in other words, if stderr="|"
. It returns
FALSE
otherwise.
$get_output_connection()
returns a connection object, to the
standard output stream of the process.
$get_error_conneciton()
returns a connection object, to the
standard error stream of the process.
$is_incomplete_output()
return FALSE
if the other end of
the standard output connection was closed (most probably because the
process exited). It return TRUE
otherwise.
$is_incomplete_error()
return FALSE
if the other end of
the standard error connection was closed (most probably because the
process exited). It return TRUE
otherwise.
$read_all_output()
waits for all standard output from the process.
It does not return until the process has finished.
Note that this process involves waiting for the process to finish,
polling for I/O and potentically several readLines()
calls.
It returns a character scalar. This will return content only if
stdout="|"
was used. Otherwise, it will throw an error.
$read_all_error()
waits for all standard error from the process.
It does not return until the process has finished.
Note that this process involves waiting for the process to finish,
polling for I/O and potentically several readLines()
calls.
It returns a character scalar. This will return content only if
stderr="|"
was used. Otherwise, it will throw an error.
$read_all_output_lines()
waits for all standard output lines
from a process. It does not return until the process has finished.
Note that this process involves waiting for the process to finish,
polling for I/O and potentically several readLines()
calls.
It returns a character vector. This will return content only if
stdout="|"
was used. Otherwise, it will throw an error.
$read_all_error_lines()
waits for all standard error lines from
a process. It does not return until the process has finished.
Note that this process involves waiting for the process to finish,
polling for I/O and potentically several readLines()
calls.
It returns a character vector. This will return content only if
stderr="|"
was used. Otherwise, it will throw an error.
$get_output_file()
if the stdout
argument was a filename,
this returns the absolute path to the file. If stdout
was "|"
or
NULL
, this simply returns that value.
$get_error_file()
if the stderr
argument was a filename,
this returns the absolute path to the file. If stderr
was "|"
or
NULL
, this simply returns that value.
$poll_io()
polls the process's connections for I/O. See more in
the Polling section, and see also the poll()
function
to poll on multiple processes.
print(p)
or p$print()
shows some information about the
process on the screen, whether it is running and it's process id, etc.
# NOT RUN {
# CRAN does not like long-running examples
# }
# NOT RUN {
p <- process$new("sleep", "2")
p$is_alive()
p
p$kill()
p$is_alive()
p$restart()
p$is_alive()
Sys.sleep(3)
p$is_alive()
# }
# NOT RUN {
# }
Run the code above in your browser using DataCamp Workspace