data-raw/roxygenex.R

#' External process#'#' 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 \code{pipe} 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.#'#' @section Usage:#' \preformatted{p <- process$new(command = NULL, args, commandline = NULL,#' stdout = TRUE, stderr = TRUE)#'#' 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)#' }#'#' @section Arguments:#' \describe{#' \item{p}{A \code{process} object.}#' \item{command}{Character scalar, the command to run. It will be#' escaped via \code{\link[base]{shQuote}}.}#' \item{args}{Character vector, arguments to the command. The will be#' escaped via \code{\link[base]{shQuote}}.}#' \item{commandline}{A character scalar, a full command line.#' No escaping will be performed on it.}#' \item{stdout}{What to do with the standard output. Possible values:#' \code{FALSE}: discard it; a string, redirect it to this file,#' \code{TRUE}: redirect it to a temporary file.}#' \item{stdout}{What to do with the standard error. Possible values:#' \code{FALSE}: discard it; a string, redirect it to this file,#' \code{TRUE}: redirect it to a temporary file.}#' \item{grace}{Grace pediod between the TERM and KILL signals, in#' seconds.}#' \item{...}{Extra arguments are passed to the#' \code{\link[base]{readLines}} function.}#' }#'#' @section Details:#' \code{$new()} starts a new process, it uses \code{\link[base]{pipe}}.#' R does \emph{not} wait for the process to finish, but returns#' immediately.#'#' \code{$is_alive()} checks if the process is alive. Returns a logical#' scalar.#'#' \code{$kill()} kills the process. It also kills all of its child#' processes. First it sends the child processes a \code{TERM} signal, and#' then after a grace period a \code{KILL} signal. Then it does the same#' for the process itself. A killed process can be restarted using the#' \code{restart} method. It returns the process itself.#'#' \code{$wait()} waits until the process finishes. Note that if the#' process never finishes, then R will never regain control. It returns#' the process itself.#'#' \code{$get_exit_code} returns the exit code of the process if it has#' finished and \code{wait} was called on it. Otherwise it will return#' \code{NULL}.#'#' \code{$restart()} restarts a process. It returns the process itself.#'#' \code{$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.#'#' \code{$read_error_lines()} is similar to \code{$read_output_lines}, but#' it reads from the standard error stream.#'#' \code{$can_read_output()} checks if there is any standard output#' immediately available.#'#' \code{$can_read_error()} checks if there is any standard error#' immediately available.#'#' \code{$is_eof_output()} checks if the standard output stream has#' ended. This means that the process is finished and all output has#' been processed.#'#' \code{$is_eof_error()} checks if the standard error stream has#' ended. This means that the process is finished and all output has#' been processed.#'#' \code{$get_output_connection()} returns a connection object, to the#' standard output stream of the process.#'#' \code{$get_error_conneciton()} returns a connection object, to the#' standard error stream of the process.#'#' \code{print(p)} or \code{p$print()} shows some information about the#' process on the screen, whether it is running and it's process id, etc.#'#' @importFrom R6 R6Class#' @name process#' @examples#' 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()#'NULL