88# ' @param substitute Controls whether `expr` should be
99# ' `substitute()`:d or not.
1010# '
11- # ' @param globals (optional) a logical, a character vector, a named list, or
12- # ' a [Globals][globals::Globals] object. If TRUE, globals are identified by code
11+ # ' @param globals (optional) a logical, a character vector, a named list, or a
12+ # ' [Globals][globals::Globals] object. If TRUE, globals are identified by code
1313# ' inspection based on `expr` and `tweak` searching from environment
1414# ' `envir`. If FALSE, no globals are used. If a character vector, then
1515# ' globals are identified by lookup based their names `globals` searching
1919# ' @param label (optional) Label of the future (where applicable, becomes the
2020# ' job name for most job schedulers).
2121# '
22- # ' @param conf A batchtools configuration environment.
23- # '
24- # ' @param cluster.functions A batchtools [ClusterFunctions][batchtools::ClusterFunctions]
25- # ' object.
26- # '
27- # ' @param resources A named list passed to the batchtools template (available
28- # ' as variable `resources`).
22+ # ' @param resources (optional) A named list passed to the batchtools template
23+ # ' (available as variable `resources`).
2924# '
3025# ' @param workers (optional) The maximum number of workers the batchtools
3126# ' backend may use at any time. Interactive and "local" backends can only
32- # ' process one future at the time, whereas HPC backends where futures are
33- # ' resolved via separate jobs on a scheduler, the default is to assume an
34- # ' infinite number of workers.
27+ # ' process one future at the time (`workers = 1L`), whereas HPC backends,
28+ # ' where futures are resolved via separate jobs on a scheduler, can have
29+ # ' multiple workers. In the latter, the default is `workers = NULL`, which
30+ # ' will resolve to `getOption("future.batchtools.workers")`. If that is not
31+ # ' specified, the value of environment variable `R_FUTURE_BATCHTOOLS_WORKERS`
32+ # ' will be used. If neither are specified, then the default is `100`.
3533# '
3634# ' @param finalize If TRUE, any underlying registries are
3735# ' deleted when this object is garbage collected, otherwise not.
3836# '
37+ # ' @param conf.file (optional) A batchtools configuration file.
38+ # '
39+ # ' @param cluster.functions (optional) A batchtools
40+ # ' [ClusterFunctions][batchtools::ClusterFunctions] object.
41+ # '
42+ # ' @param registry (optional) A named list of settings to control the setup
43+ # ' of the batchtools registry.
44+ # '
3945# ' @param \ldots Additional arguments passed to [future::Future()].
4046# '
4147# ' @return A BatchtoolsFuture object
4753BatchtoolsFuture <- function (expr = NULL , envir = parent.frame(),
4854 substitute = TRUE ,
4955 globals = TRUE , packages = NULL ,
50- label = NULL , cluster.functions = NULL ,
51- resources = list (), workers = NULL ,
56+ label = NULL ,
57+ resources = list (),
58+ workers = NULL ,
5259 finalize = getOption(" future.finalize" TRUE ),
60+ conf.file = findConfFile(),
61+ cluster.functions = NULL ,
62+ registry = list (),
5363 ... ) {
5464 if (substitute ) expr <- substitute(expr )
5565
5666 if (! is.null(label )) label <- as.character(label )
5767
5868 if (! is.null(cluster.functions )) {
5969 stop_if_not(is.list(cluster.functions ))
70+ stop_if_not(inherits(cluster.functions , " ClusterFunctions"
71+ } else if (missing(conf.file )) {
72+ # # BACKWARD COMPATILITY: Only when calling BatchtoolsFuture() directly
73+ cluster.functions <- makeClusterFunctionsInteractive(external = FALSE )
74+ } else {
75+ # # If 'cluster.functions' is not specified, then 'conf.file' must
76+ # # exist
77+ if (! file_test(" -f" conf.file )) {
78+ stop(" No such batchtools configuration file: " conf.file ))
79+ }
6080 }
61-
81+
6282 if (is.function(workers )) workers <- workers()
6383 if (! is.null(workers )) {
6484 stop_if_not(length(workers ) > = 1 )
@@ -70,6 +90,11 @@ BatchtoolsFuture <- function(expr = NULL, envir = parent.frame(),
7090 }
7191 }
7292
93+ stop_if_not(is.list(registry ))
94+ if (length(registry ) > 0L ) {
95+ stopifnot(! is.null(names(registry )), all(nzchar(names(registry ))))
96+ }
97+
7398 stop_if_not(is.list(resources ))
7499
75100 # # Record globals
@@ -84,10 +109,12 @@ BatchtoolsFuture <- function(expr = NULL, envir = parent.frame(),
84109 future $ packages <- unique(c(packages , gp $ packages ))
85110
86111 # # Create batchtools registry
87- reg <- temp_registry(label = future $ label )
88- if (! is.null(cluster.functions )) { # ## FIXME
89- reg $ cluster.functions <- cluster.functions
90- }
112+ reg <- temp_registry(
113+ label = future $ label ,
114+ conf.file = conf.file ,
115+ cluster.functions = cluster.functions ,
116+ config = registry
117+ )
91118 debug <- getOption(" future.debug" FALSE )
92119 if (debug ) mprint(reg )
93120
@@ -126,13 +153,15 @@ print.BatchtoolsFuture <- function(x, ...) {
126153 # # Ask for status once
127154 status <- status(x )
128155 printf(" batchtools status: %s\n " status ), collapse = " , "
129- if (" error" %in% status ) printf(" Error: %s\n " x ))
156+ if (" error" %in% status ) {
157+ printf(" Error captured by batchtools: %s\n " x ))
158+ }
130159
131160 if (is_na(status )) {
132161 printf(" batchtools %s: Not found (happens when finished and deleted)\n "
133162 class(reg ))
134163 } else {
135- printf(" batchtools Registry:\n "
164+ printf(" batchtools Registry:\n "
136165 printf(" File dir exists: %s\n " " -d" reg $ file.dir ))
137166 printf(" Work dir exists: %s\n " " -d" reg $ work.dir ))
138167 try(print(reg ))
@@ -504,8 +533,9 @@ await.BatchtoolsFuture <- function(future, cleanup = TRUE,
504533 }
505534 } else if (" error" %in% stat ) {
506535 cleanup <- FALSE
507- msg <- sprintf(" BatchtoolsError in %s ('%s'): %s"
508- class(future )[1 ], label , loggedError(future ))
536+ msg <- sprintf(
537+ " BatchtoolsFutureError for %s ('%s') captured by batchtools: %s"
538+ class(future )[1 ], label , loggedError(future ))
509539 stop(BatchtoolsFutureError(msg , future = future ))
510540 } else if (" expired" %in% stat ) {
511541 cleanup <- FALSE
0 commit comments