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, commandline = NULL,
stdout = TRUE, stderr = TRUE, cleanup = TRUE,
echo_cmd = FALSE, windows_verbatim_args = FALSE,
windows_hide_window = FALSE)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_lines(...) p$read_error_lines(...) 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)
A process object.
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 shQuote. See
normalizePath for tilde-expansion.
Character vector, arguments to the command. They will be used as is, without a shell. They don't need to be escaped.
A character scalar, a full command line.
On Unix systems it runs the a shell: sh -c <commandline>.
On Windows it uses the cmd shell:
cmd /c <commandline>. If you want more control, then call
your chosen shell directly.
What to do with the standard output. Possible values:
FALSE: discard it; a string, redirect it to this file,
TRUE: redirect it to a temporary file, "|": create an
R connection for it.
What to do with the standard error. Possible values:
FALSE: discard it; a string, redirect it to this file,
TRUE: redirect it to a temporary file, "|": create an
R connection for it.
Whether to kill the process (and its children)
if the process object is garbage collected.
Whether to print the command to the screen before running it.
Whether to omit quoting the arguments on Windows. It is ignored on other platforms.
Whether to hide the application's window on Windows. It is ignored on other platforms.
An integer scalar, the id of the signal to send to
the process. See pskill for the list of
signals.
Currently not used.
Timeout in milliseconds, for the wait or the I/O polling.
Extra arguments are passed to the
readLines function.
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 processx 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.
$read_output_lines() reads 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.
$read_error_lines() is similar to $read_output_lines, but
it reads from the standard error stream.
$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.
$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.
$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.
$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.
$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