R: External process

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

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

### 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]