process {callr}R Documentation

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,
                 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)

Arguments

Details

$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.

Polling

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).

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

## End(Not run)


[Package callr version 2.0.2 Index]