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 DataLab