processx (version 1.0.0.9000)

process: External process

Description

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.

Usage

p <- process$new(command = NULL, args, commandline = NULL,
                 stdout = TRUE, stderr = TRUE, cleanup = TRUE,
                 echo_cmd = FALSE) p$is_alive()
p$kill(grace = 0.1)
p$wait()
p$get_exit_status()
p$restart() p$read_output_lines(...)
p$read_error_lines(...)
p$can_read_output()
p$can_read_error()
p$is_eof_output()
p$is_eof_error()
p$get_output_connection()
p$get_error_connection() print(p)

Arguments

p

A process object.

command

Character scalar, the command to run. It will be escaped via shQuote.

args

Character vector, arguments to the command. They will be escaped via shQuote.

commandline

A character scalar, a full command line. No escaping will be performed on it.

stdout

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.

stdout

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.

cleanup

Whether to kill the process if the process object is garbage collected.

echo_cmd

Whether to print the command to the screen before running it.

grace

Grace pediod between the TERM and KILL signals, in seconds.

...

Extra arguments are passed to the readLines function.

Details

$new() starts a new process, it uses system. R does not wait for the process to finish, but returns immediately. $is_alive() checks if the process is alive. Returns a logical scalar. $kill() kills the process. It also kills all of its child processes. First it sends the child processes a TERM signal, and then after a grace period a KILL signal. Then it does the same for the process itself. A killed process can be restarted using the restart method. It returns the process itself. $wait() waits until the process finishes. Note that if the process never finishes, then R will never regain control. It returns the process itself. $get_exit_code returns the exit code of the process if it has finished and wait was called on it. Otherwise it will return NULL. $restart() restarts a process. It returns the process itself. $read_output_lines() reads from standard output of the process. If the standard output was not requested, 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. $can_read_output() checks if there is any standard output immediately available. $can_read_error() checks if there is any standard error immediately available. $is_eof_output() checks if the standard output stream has ended. This means that the process is finished and all output has been processed. $is_eof_error() checks if the standard error stream has ended. This means that the process is finished and all output has been processed. $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. print(p) or p$print() shows some information about the process on the screen, whether it is running and it's process id, etc.

Examples

# 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()
## ---------------------------------------------