Better documentation for 'batchtools_interactive', 'batchtools_local', and 'batchtools_bash'

Author: HenrikBengtsson

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: future.batchtools
-Version: 0.12.2-9914
+Version: 0.12.2-9915
 Depends:
     R (>= 3.2.0),
     parallelly,

NAMESPACE

@@ -56,6 +56,7 @@ export(batchtools_ssh)
 export(batchtools_torque)
 export(loggedError)
 export(loggedOutput)
+export(makeClusterFunctionsBash)
 importFrom(batchtools,Worker)
 importFrom(batchtools,batchExport)
 importFrom(batchtools,batchMap)

R/BatchtoolsFutureBackend-class.R

@@ -2,10 +2,6 @@
 #'
 #' @inheritParams future::FutureBackend
 #'
-#' @param resources (optional) A named list passed to the \pkg{batchtools}
-#' template (available as variable `resources`).  See Section 'Resources'
-#' in [batchtools::submitJobs()] more details.
-#'
 #' @param workers (optional) The maximum number of workers the batchtools
 #' backend may use at any time.   Interactive and "local" backends can only
 #' process one future at the time (`workers = 1L`), whereas HPC backends,
@@ -15,32 +11,42 @@
 #' \code{getOption("\link{future.batchtools.workers}")}.
 #' If neither are specified, then the default is `100`.
 #'
-#' @param finalize If TRUE, any underlying registries are
-#' deleted when this object is garbage collected, otherwise not.
+#' @param finalize If TRUE, a future's \pkg{batchtools}
+#' \link[batchtools:makeRegistry]{Registry} is automatically deleted when
+#' the future is garbage collected, otherwise not.
 #'
-#' @param conf.file (optional) A batchtools configuration file.
+#' @param cluster.functions (optional) Assigned as-is to the each future's
+#' \pkg{batchtools} \link[batchtools:makeRegistry]{Registry}.
 #'
-#' @param cluster.functions (optional) A batchtools
-#' [ClusterFunctions][batchtools::ClusterFunctions] object.
+#' @param registry (optional) A named list of settings applied to each
+#' future's \pkg{batchtools} \link[batchtools:makeRegistry]{Registry}.
+#' This is a more convenient alternative to using argument `conf.file`.
 #'
-#' @param registry (optional) A named list of settings to control the setup
-#' of the batchtools registry.
+#' @param conf.file (optional) A "batchtools-configuration" R script, which
+#' is sourced when each future's \pkg{batchtools}
+#' \link[batchtools:makeRegistry]{Registry} is created. Any variables
+#' created by this script is assigned to the registry.
+#' The default file is the one found by [batchtools::findConfFile()], if any.
+#'
+#' @param resources (optional) A named list passed to the \pkg{batchtools}
+#' job-script template as variable `resources`.  See Section 'Resources'
+#' in [batchtools::submitJobs()] more details.
 #'
 #' @param \ldots Not used.
 #'
 #' @return A [future::FutureBackend] object of class BatchtoolsFutureBackend 
 #'
 #' @aliases BatchtoolsUniprocessFutureBackend BatchtoolsMultiprocessFutureBackend
-#' @rdname BatchtoolsFuture
 #' @importFrom utils file_test
 #' @importFrom future FutureBackend
 #' @keywords internal
 #' @export
-BatchtoolsFutureBackend <- function(workers = NULL, resources = list(),
+BatchtoolsFutureBackend <- function(
+                             workers = NULL, resources = list(),
                              finalize = getOption("future.finalize", TRUE),
-                             conf.file = findConfFile(),
                              cluster.functions = NULL,
                              registry = list(),
+                             conf.file = findConfFile(),
                              interrupts = TRUE,
                              ...) {
   assert_no_positional_args_but_first()
@@ -103,6 +109,8 @@ BatchtoolsFutureBackend <- function(workers = NULL, resources = list(),
 }
 
 
+#' @inheritParams BatchtoolsFutureBackend
+#'
 #' @export
 BatchtoolsUniprocessFutureBackend <- function(workers = 1L, ...) {
   assert_no_positional_args_but_first()
@@ -111,6 +119,8 @@ BatchtoolsUniprocessFutureBackend <- function(workers = 1L, ...) {
   core
 }
 
+#' @inheritParams BatchtoolsFutureBackend
+#'
 #' @export
 BatchtoolsMultiprocessFutureBackend <- function(...) {
   assert_no_positional_args_but_first()

R/batchtools_bash.R

@@ -1,13 +1,17 @@
-#' @inheritParams batchtools_custom
-#' @inheritParams batchtools_template
+#' @inheritParams BatchtoolsTemplateFutureBackend
+#' @rdname BatchtoolsFutureBackend
+#' @keywords internal
 #'
 #' @export
-BatchtoolsBashFutureBackend <- function(..., template = "bash") {
+BatchtoolsBashFutureBackend <- function(...,
+    cluster.functions = makeClusterFunctionsBash(template = template),
+    template = "bash") {
   assert_no_positional_args_but_first()
 
   core <- BatchtoolsMultiprocessFutureBackend(
-    cluster.functions = makeClusterFunctionsBash(template = template),
-    ...
+    ...,
+    cluster.functions = cluster.functions,
+    template = template
   )
 
   core[["futureClasses"]] <- c("BatchtoolsBashFuture", core[["futureClasses"]])
@@ -16,8 +20,55 @@ BatchtoolsBashFutureBackend <- function(..., template = "bash") {
 }
 
 
+#' A batchtools bash backend that resolves futures in a single background R session via Bash
+#'
+#' The `batchtools_bash` backend was added to illustrate how to write a
+#' custom \pkg{future.batchtools} backend that uses a job-script template.
+#' Please see the source code, for details.
+#'
+#' @inheritParams BatchtoolsFutureBackend
+#' @inheritParams BatchtoolsTemplateFutureBackend
+#' @inheritParams BatchtoolsBashFutureBackend
+#'
+#' @param template (optional) Name of job-script template to be searched
+#' for by [batchtools::findTemplateFile()]. If not found, it defaults to
+#' the `templates/bash.tmpl` part of this package (see below).
+#'
+#' @param \ldots Not used.
+#'
+#' @details
+#' Batchtools bash futures uses \pkg{batchtools} cluster functions
+#' created by [makeClusterFunctionsBash()] and requires that Bash is
+#' installed on the current machine.
+#'
+#' The default template script `templates/bash.tmpl` can be found in:
+#'
+#' ```r
+#' system.file("templates", "bash.tmpl", package = "future.batchtools")
+#' ```
+#'
+#' and comprise:
+#'
+#' `r paste(c("\x60\x60\x60bash", readLines("inst/templates/bash.tmpl"), "\x60\x60\x60"), collapse = "\n")`
+#'
+#' @examplesIf interactive()
+#' plan(batchtools_bash)
+#'
+#' message("Main process ID: ", Sys.getpid())
+#'
+#' f <- future(Sys.getpid())
+#' pid <- value(f)
+#' message("Workers process ID: ", pid)
+#' 
 #' @export
-batchtools_bash <- function(..., envir = parent.frame(), template = "bash") {
+batchtools_bash <- function(
+  cluster.functions = makeClusterFunctionsBash(template = "bash"),
+  template = "bash",
+  registry = list(),
+  conf.file = findConfFile(),
+  resources = list(),
+  finalize = getOption("future.finalize", TRUE),
+  ...) {
  stop("INTERNAL ERROR: The future.batchtools::batchtools_bash() must never be called directly")
 }
 class(batchtools_bash) <- c(
@@ -31,8 +82,17 @@ attr(batchtools_bash, "init") <- TRUE
 attr(batchtools_bash, "factory") <- BatchtoolsBashFutureBackend
 
 
+#' @inheritParams batchtools::makeClusterFunctions
+#'
+#' @return
+#' `makeClusterFunctionsBash()` returns a
+#' \link[batchtools:makeClusterFunctions]{ClusterFunctions} object.
+#'
+#' @rdname batchtools_bash
+#'
 #' @importFrom batchtools cfReadBrewTemplate cfBrewTemplate makeClusterFunctions makeSubmitJobResult
 #' @importFrom utils file_test
+#' @export
 makeClusterFunctionsBash <- function(template = "bash") {
   bin <- Sys.which("bash")
   stop_if_not(file_test("-f", bin), file_test("-x", bin))

R/batchtools_custom.R

@@ -8,7 +8,9 @@
 #'
 #' @example incl/batchtools_custom.R
 #'
-#' @aliases batchtools_custom
+#' @rdname BatchtoolsFutureBackend
+#' @keywords internal
+#'
 #' @export
 #' @importFrom batchtools findConfFile
 BatchtoolsCustomFutureBackend <- function(...) {
@@ -23,8 +25,10 @@ BatchtoolsCustomFutureBackend <- function(...) {
   core
 }
 
+#' @inheritParams BatchtoolsCustomFutureBackend
+#'
 #' @export
-batchtools_custom <- function(..., envir = parent.frame()) {
+batchtools_custom <- function(...) {
  stop("INTERNAL ERROR: The future.batchtools::batchtools_custom() must never be called directly")
 }
 class(batchtools_custom) <- c(

R/batchtools_interactive.R

@@ -1,4 +1,5 @@
-#' @inheritParams BatchtoolsFuture
+#' @rdname BatchtoolsFutureBackend
+#' @keywords internal
 #'
 #' @importFrom batchtools makeClusterFunctionsInteractive
 #' @export
@@ -15,8 +16,38 @@ BatchtoolsInteractiveFutureBackend <- function(...) {
   core
 }
 
+#' A batchtools backend that resolves futures sequentially in the current R session
+#'
+#' The batchtools interactive backend is useful for verifying parts of your
+#' \pkg{batchtools} setup locally, while still being able to do interactive
+#' debugging.
+#' An alternative to the batchtools interactive backend is to use
+#' `plan(future::sequential)`, which is a faster way process futures
+#' sequentially and that also can be debugged interactively.
+#'
+#' @inheritParams BatchtoolsFutureBackend
+#' @inheritParams BatchtoolsInteractiveFutureBackend
+#'
+#' @param \ldots Not used.
+#'
+#' @details
+#' Batchtools interactive futures uses \pkg{batchtools} cluster functions
+#' created by [batchtools::makeClusterFunctionsInteractive()] with
+#' `external = TRUE`.
+#'
+#' @examples
+#' plan(batchtools_interactive)
+#'
+#' message("Main process ID: ", Sys.getpid())
+#'
+#' f <- future(Sys.getpid())
+#' pid <- value(f)
+#' message("Workers process ID: ", pid)
+#' 
+#' @inheritParams BatchtoolsInteractiveFutureBackend
+#'
 #' @export
-batchtools_interactive <- function(..., envir = parent.frame()) {
+batchtools_interactive <- function(...) {
  stop("INTERNAL ERROR: The future.batchtools::batchtools_interactive() must never be called directly")
 }
 class(batchtools_interactive) <- c(
@@ -27,5 +58,3 @@ attr(batchtools_interactive, "tweakable") <- c("finalize")
 attr(batchtools_interactive, "untweakable") <- c("workers")
 attr(batchtools_interactive, "init") <- TRUE
 attr(batchtools_interactive, "factory") <- BatchtoolsInteractiveFutureBackend
-
-

R/batchtools_local.R

@@ -16,7 +16,7 @@
 #' @details
 #' batchtools local futures rely on the batchtools backend set up by
 #' \code{\link[batchtools:makeClusterFunctionsInteractive]{batchtools::makeClusterFunctionsInteractive(external = TRUE)}}
-#' and batchtools interactive futures on the one set up by
+#' and batchtools interactive futures on the one sQet up by
 #' [batchtools::makeClusterFunctionsInteractive()].
 #' These are supported by all operating systems.
 #'
@@ -30,11 +30,11 @@
 #'
 #' @example incl/batchtools_local.R
 #'
-#' @rdname BatchtoolsInteractiveFutureBackend
+#' @rdname BatchtoolsFutureBackend
+#' @keywords internal
 #'
 #' @importFrom batchtools makeClusterFunctionsInteractive
-#' @aliases batchtools_local batchtools_interactive batchtools_bash
-#' @aliases BatchtoolsLocalFutureBackend BatchtoolsInteractiveFutureBackend BatchtoolsBashFutureBackend
+#' @aliases BatchtoolsLocalFutureBackend BatchtoolsBashFutureBackend
 #' @export
 BatchtoolsLocalFutureBackend <- function(...) {
   assert_no_positional_args_but_first()
@@ -50,8 +50,37 @@ BatchtoolsLocalFutureBackend <- function(...) {
 }
 
 
+#' A batchtools backend that resolves futures sequentially in transient background R sessions
+#'
+#' The batchtools local backend is useful for verifying parts of your
+#' \pkg{batchtools} setup locally, before using a more advanced backend such
+#' as the job-scheduler backends. 
+#' An alternative to the batchtools interactive backend is to use
+#' `plan(future::cluster, workers = I(1))`.
+#'
+#' @inheritParams BatchtoolsFutureBackend
+#' @inheritParams BatchtoolsLocalFutureBackend
+#'
+#' @param \ldots Not used.
+#'
+#' @details
+#' Batchtools local futures uses \pkg{batchtools} cluster functions
+#' created by [batchtools::makeClusterFunctionsInteractive()] with
+#' `external = TRUE`.
+#'
+#' @examples
+#' plan(batchtools_local)
+#'
+#' message("Main process ID: ", Sys.getpid())
+#'
+#' f <- future(Sys.getpid())
+#' pid <- value(f)
+#' message("Workers process ID: ", pid)
+#' 
+#' @inheritParams BatchtoolsLocalFutureBackend
+#'
 #' @export
-batchtools_local <- function(..., envir = parent.frame()) {
+batchtools_local <- function(...) {
  stop("INTERNAL ERROR: The future.batchtools::batchtools_local() must never be called directly")
 }
 class(batchtools_local) <- c(

R/batchtools_multicore.R

@@ -23,10 +23,13 @@
 #' The batchtools multicore backend only works on operating systems
 #' supporting the `ps` command-line tool, e.g. Linux and macOS.
 #'
+#' @rdname BatchtoolsFutureBackend
+#' @keywords internal
+#'
+#' @aliases batchtools_custom batchtools_multicore
 #' @importFrom batchtools makeClusterFunctionsMulticore
 #' @importFrom parallelly availableCores supportsMulticore
 #' @importFrom tools pskill
-#' @keywords internal
 #' @export
 BatchtoolsMulticoreFutureBackend <- function(workers = availableCores(constraints = "multicore"), ...) {
   assert_no_positional_args_but_first()
@@ -68,9 +71,10 @@ BatchtoolsMulticoreFutureBackend <- function(workers = availableCores(constraint
 }
 
 
-#' @rdname BatchtoolsMulticoreFutureBackend
+#' @inheritParams BatchtoolsMulticoreFutureBackend
+#'
 #' @export
-batchtools_multicore <- function(..., workers = availableCores(constraints = "multicore"), envir = parent.frame()) {
+batchtools_multicore <- function(..., workers = availableCores(constraints = "multicore")) {
  stop("INTERNAL ERROR: The future.batchtools::batchtools_multicore() must never be called directly")
 }
 class(batchtools_multicore) <- c(

R/batchtools_ssh.R

@@ -9,11 +9,6 @@
 #'
 #' @inheritParams BatchtoolsFutureBackend
 #'
-#' @param workers The number of SSH processes to be
-#' available for concurrent batchtools SSH futures.
-#' @param \ldots Additional arguments passed
-#' to [BatchtoolsFutureBackend()].
-#'
 #' @return An object of class `BatchtoolsMulticoreFuture`.
 #'
 #' @details
@@ -22,9 +17,10 @@
 #' The batchtools SSH backend only works on operating systems
 #' supporting the `ssh` and `ps` command-line tool, e.g. Linux and macOS.
 #'
-#' @importFrom parallelly availableWorkers
-#'
+#' @rdname BatchtoolsFutureBackend
 #' @keywords internal
+#'
+#' @importFrom parallelly availableWorkers
 #' @importFrom batchtools makeClusterFunctionsSSH
 #' @importFrom parallelly availableCores
 #' @export
@@ -76,8 +72,10 @@ BatchtoolsSSHFutureBackend <- function(workers = availableWorkers(), ...) {
 }
 
 
+#' @inheritParams BatchtoolsSSHFutureBackend
+#'
 #' @export
-batchtools_ssh <- function(..., workers = availableWorkers(), envir = parent.frame()) {
+batchtools_ssh <- function(..., workers = availableWorkers()) {
  stop("INTERNAL ERROR: The future.batchtools::batchtools_ssh() must never be called directly")
 }
 class(batchtools_ssh) <- c(