callr (version 2.0.2)

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

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

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

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.

Examples

Run this code
# 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