Vignette that uses r_session to create a task queue (#112)

Vignette that uses r_session to create a task queue

.Rbuildignore

@@ -15,3 +15,5 @@
 ^README\.Rmd$
 ^inst/header\.md$
 ^README\.html$
+^doc$
+^Meta$

.gitignore

@@ -14,3 +14,6 @@
 /src/callr.so
 /inst/env.rds
 /README.html
+inst/doc
+doc
+Meta

DESCRIPTION

@@ -25,8 +25,15 @@ Suggests:
     cliapp,
     covr,
     crayon,
+    knitr,
     pingr,
     ps,
+    rmarkdown,
+    rprojroot,
+    spelling,
     testthat,
+    tibble,
     withr
 Encoding: UTF-8
+VignetteBuilder: knitr
+Language: en-US

NEWS.md

@@ -1,5 +1,5 @@
 
-# dev
+# development version
 
 * New `$traceback()` method for `r_session`, to run `traceback()` in the
   subprocess, after an error.
@@ -42,9 +42,9 @@
   `callr_session_result`.
 
 * `r_session$run*()` handle interrupts properly. It tries to interrupt
-  the background process fist, kills it if it is not interruptable,
+  the background process fist, kills it if it is not interruptible,
   and then re-throws the interrupt condition, going back to the top level
-  prompt if the re-thrown condition is un-caught.
+  prompt if the re-thrown condition is uncaught.
 
 # callr 3.0.0
 
@@ -82,19 +82,19 @@ option.
   https://github.com/wch/r-source/commit/924582943706100e88a11d6bb0585d25779c91f5
   #37, #38
 
-* Fix a race condition on Windows, when creating named pipes for stdout
-  or stderr. The client sometimes didn't wait for the server, and callr
+* Fix a race condition on Windows, when creating named pipes for `stdout`
+  or `stderr`. The client sometimes didn't wait for the server, and callr
   failed with ERROR_PIPE_BUSY (231, All pipe instances are busy).
 
 # callr 2.0.1
 
-* Fix compilation issues on CRAN's Solaris machine
+* Fix compilation issues on Solaris
 
-* Fix a test failure on CRAN's macOS machine
+* Fix a test failure on macOS
 
 # callr 2.0.0
 
-* Run R or R CMD * in the background, see `r_bg()`, `rcmd_bg()`,
+* Run R or `R CMD` in the background, see `r_bg()`, `rcmd_bg()`,
   and also `r_process` and `rcmd_process`
 
 * The defaults for `r()` are safer now, the match the defaults of
@@ -112,7 +112,7 @@ option.
 
 * Support timeouts, via the `timeout` argument
 
-* Fix bug when stdout and stderr are redirected to the same file
+* Fix bug when `stdout` and `stderr` are redirected to the same file
 
 * `rcmd_safe_env()` to allow extending the environment variables set in
   safe mode

R/eval.R

@@ -13,7 +13,7 @@
 #'   and `R_PDFVIEWER` to avoid starting a browser or a PDF viewer.
 #'   See [rcmd_safe_env()].
 #'
-#' The pre-2.0.0 `r()` function is called [r_copycat()] now.
+#' The `r()` function from before 2.0.0 is called [r_copycat()] now.
 #'
 #' @param func Function object to call in the new R process.
 #'   The function should be self-contained and only refer to
@@ -34,8 +34,8 @@
 #'   works just fine.
 #' @param args Arguments to pass to the function. Must be a list.
 #' @param libpath The library path.
-#' @param repos The *repos* option. If `NULL`, then no
-#'   *repos* option is set. This options is only used if
+#' @param repos The `repos` option. If `NULL`, then no
+#'   `repos` option is set. This options is only used if
 #'   `user_profile` or `system_profile` is set `FALSE`,
 #'   as it is set using the system or the user profile.
 #' @param stdout The name of the file the standard output of
@@ -50,7 +50,7 @@
 #'   error. If nothing was sent to the standard error, then this file
 #'   will be empty. This argument can be the same file as `stdout`,
 #'   in which case they will be correctly interleaved. If this is the
-#'   string `"2>&1"`, then standard error is redictd to standard output.
+#'   string `"2>&1"`, then standard error is redirected to standard output.
 #' @param error What to do if the remote process throws an error.
 #'   See details below.
 #' @param poll_connection Whether to have a control connection to

R/rcmd-bg.R

@@ -1,5 +1,5 @@
 
-#' Run an R CMD command in the background
+#' Run an `R CMD` command in the background
 #'
 #' The child process is started in the background, and the function
 #' return immediately.
@@ -12,7 +12,7 @@
 #'   constructor.
 #' @return It returns a [process] object.
 #'
-#' @family R CMD commands
+#' @family \code{R CMD} commands
 #' @export
 
 rcmd_bg <- function(cmd, cmdargs = character(), libpath = .libPaths(),

R/rcmd-process.R

@@ -1,5 +1,5 @@
 
-#' External R CMD Process
+#' External `R CMD` Process
 #'
 #' An `R CMD *` command that runs in the background. This is an R6 class
 #' that extends the [process] class.

R/rcmd.R

@@ -1,7 +1,7 @@
 
-#' Run an R CMD command
+#' Run an `R CMD` command
 #'
-#' Run an R CMD command form within R. This will usually start
+#' Run an `R CMD` command form within R. This will usually start
 #' another R process, from a shell script.
 #'
 #' Starting from `callr` 2.0.0, `rcmd()` has safer defaults, the same as
@@ -10,9 +10,9 @@
 #'
 #' @param cmd Command to run. See `R --help` from the command
 #'   line for the various commands. In the current version of R (3.2.4)
-#'   these are: BATCH, COMPILE, SHLIB, INSTALL, REMOVE, build, check,
-#'   LINK, Rprof, Rdconv, Rd2pdf, Rd2txt, Stangle, Sweave, Rdiff, config,
-#'   javareconf, rtags.
+#'   these are: `BATCH`, `COMPILE`, `SHLIB`, `INSTALL`, `REMOVE`, `build`,
+#'   `check`, `LINK`, `Rprof`, `Rdconv`, `Rd2pdf`, `Rd2txt`, `Stangle`,
+#'   `Sweave`, `Rdiff`, `config`, `javareconf`, `rtags`.
 #' @param cmdargs Command line arguments.
 #' @param stdout Optionally a file name to send the standard output to.
 #' @param stderr Optionally a file name to send the standard error to.
@@ -34,7 +34,7 @@
 #'   exit status (`$status`) of the external `R CMD` command, and
 #'   whether a timeout was reached (`$timeout`).
 #'
-#' @family R CMD commands
+#' @family \code{R CMD} commands
 #' @export
 #'
 #' @examples
@@ -77,7 +77,7 @@ rcmd_safe <- rcmd
 #'   style file names.
 #' * `R_TESTS=""` This variable is set by `R CMD check`, and makes the
 #'   child R process load a startup file at startup, from the current
-#'   working directory, that is assumed to be the `/test` dirctory
+#'   working directory, that is assumed to be the `/test` directory
 #'   of the package being checked. If the current working directory is
 #'   changed to something else (as it typically is by `testthat`, then R
 #'   cannot start. Setting it to the empty string ensures that `callr` can
@@ -108,7 +108,7 @@ rcmd_safe_env <- function() {
   vars
 }
 
-#' Call and R CMD command, while mimicking the current R session
+#' Call and `R CMD` command, while mimicking the current R session
 #'
 #' This function is similar to [rcmd()], but it has slightly different
 #' defaults:
@@ -118,7 +118,7 @@ rcmd_safe_env <- function() {
 #' @inheritParams rcmd
 #' @param ... Additional arguments are passed to [rcmd()].
 #'
-#' @family R CMD commands
+#' @family \code{R CMD} commands
 #' @export
 
 rcmd_copycat <- function(cmd, cmdargs = character(), libpath = .libPaths(),

R/result.R

@@ -1,8 +1,8 @@
 
 #' Read the result object from the output file, or the error
 #'
-#' Even if an error happens, the ouput file might still exist,
-#' because saveRDS creates the file before evaluating its object
+#' Even if an error happens, the output file might still exist,
+#' because [saveRDS()] creates the file before evaluating its object
 #' argument. So we need to check for the error file to decide
 #' if an error happened.
 #'

R/rscript.R

@@ -1,8 +1,8 @@
 
 #' Run an R script
 #'
-#' It uses the `Rscript` program corresponding to the current R vesion,
-#' to run the script. It streams stdout and stderr of the process.
+#' It uses the `Rscript` program corresponding to the current R version,
+#' to run the script. It streams `stdout` and `stderr` of the process.
 #'
 #' @inheritParams rcmd
 #' @param script Path of the script to run.
@@ -50,7 +50,7 @@ rscript_load_hook_color <- function(color) {
   paste0(deparse(expr), "\n")
 }
 
-#' External Rscript process
+#' External `Rscript` process
 #'
 #' An `Rscript script.R` command that runs in the background. This is an
 #' R6 class that extends the [process] class.

README.Rmd

@@ -33,7 +33,7 @@ if (knitr::opts_knit$get("rmarkdown.pandoc.to") == "html") {
 * Shows and/or collects the standard output and standard error of the
   subprocess.
 * Supports both one-off and persistent R subprocesses.
-* Calls the fucntion synchronously or asynchronously (in the background).
+* Calls the function synchronously or asynchronously (in the background).
 * Can call `R CMD` commands, synchronously or asynchronously.
 * Can call R scripts, synchronously or asynchronously.
 * Provides extensible `r_process`, `rcmd_process` and `rscript_process`
@@ -186,7 +186,7 @@ function call. Some of the handiest methods are:
 * `get_exit_status()` to query the exit status of a finished process.
 * `get_result()` to collect the return value of the R function call.
 * `intertupt()` to send an interrupt to the process. This is equivalent
-  to a CTRL+C keypress, and the R process might ignore it.
+  to a `CTRL+C` key press, and the R process might ignore it.
 * `is_alive()` to check if the process is alive.
 * `kill()` to terminate the process.
 * `poll_io()` to wait for any standard output, standard error, or the

README.md

@@ -44,7 +44,7 @@ Features
 -   Shows and/or collects the standard output and standard error of the
     subprocess.
 -   Supports both one-off and persistent R subprocesses.
--   Calls the fucntion synchronously or asynchronously (in the
+-   Calls the function synchronously or asynchronously (in the
     background).
 -   Can call `R CMD` commands, synchronously or asynchronously.
 -   Can call R scripts, synchronously or asynchronously.
@@ -258,7 +258,7 @@ function call. Some of the handiest methods are:
 -   `get_exit_status()` to query the exit status of a finished process.
 -   `get_result()` to collect the return value of the R function call.
 -   `intertupt()` to send an interrupt to the process. This is
-    equivalent to a CTRL+C keypress, and the R process might ignore it.
+    equivalent to a `CTRL+C` key press, and the R process might ignore it.
 -   `is_alive()` to check if the process is alive.
 -   `kill()` to terminate the process.
 -   `poll_io()` to wait for any standard output, standard error, or the

inst/WORDLIST

@@ -0,0 +1,13 @@
+cliapp
+finalizer
+igraph
+interruptible
+macOS
+pkgdown
+pollable
+processx
+subcommand
+subprocess
+subprocesses
+tibble
+traceback