Batchtools futures for custom batchtools configuration

batchtools_custom(
  expr,
  envir = parent.frame(),
  substitute = TRUE,
  globals = TRUE,
  label = NULL,
  resources = list(),
  workers = NULL,
  conf.file = findConfFile(),
  cluster.functions = NULL,
  registry = list(),
  ...
)

Arguments

expr

The R expression to be evaluated

envir

The environment in which global environment should be located.

substitute

Controls whether expr should be substitute():d or not.

globals

(optional) a logical, a character vector, a named list, or a Globals object. If TRUE, globals are identified by code inspection based on expr and tweak searching from environment envir. If FALSE, no globals are used. If a character vector, then globals are identified by lookup based their names globals searching from environment envir. If a named list or a Globals object, the globals are used as is.

label

(optional) Label of the future (where applicable, becomes the job name for most job schedulers).

resources

(optional) A named list passed to the batchtools template (available as variable resources). See Section 'Resources' in batchtools::submitJobs() more details.

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, where futures are resolved via separate jobs on a scheduler, can have multiple workers. In the latter, the default is workers = NULL, which will resolve to getOption("future.batchtools.workers"). If that is not specified, the value of environment variable R_FUTURE_BATCHTOOLS_WORKERS will be used. If neither are specified, then the default is 100.

conf.file

(character) A batchtools configuration file as for instance returned by batchtools::findConfFile().

cluster.functions

A ClusterFunctions object.

registry

(optional) A named list of settings to control the setup of the batchtools registry.

...

Additional arguments passed to BatchtoolsFuture().

Value

An object of class BatchtoolsFuture.

Examples

options(error = function(...) { print(traceback()) }) cf <- batchtools::makeClusterFunctionsInteractive(external = TRUE) print(cf)
#> ClusterFunctions for mode: Interactive #> List queued Jobs : FALSE #> List running Jobs: FALSE #> Kill Jobs : FALSE #> Hooks : -
str(cf)
#> List of 11 #> $ name : chr "Interactive" #> $ submitJob :function (reg, jc) #> $ killJob : NULL #> $ listJobsQueued : NULL #> $ listJobsRunning : NULL #> $ array.var : chr NA #> $ store.job.collection: logi TRUE #> $ store.job.files : logi FALSE #> $ scheduler.latency : num 0 #> $ fs.latency : num 0 #> $ hooks : list() #> - attr(*, "class")= chr "ClusterFunctions"
plan(batchtools_custom, cluster.functions = cf) print(plan())
#> batchtools_custom: #> - args: function (..., workers = NULL, envir = parent.frame(), cluster.functions = list(name = "Interactive", submitJob = function (reg, jc) { assertRegistry(reg, writeable = TRUE) assertClass(jc, "JobCollection") if (external) { runOSCommand(Rscript(), sprintf("-e \"batchtools::doJobCollection('%s', output = '%s')\"", jc$uri, jc$log.file)) } else { doJobCollection(jc, output = jc$log.file) } makeSubmitJobResult(status = 0L, batch.id = "cfInteractive") }, killJob = NULL, listJobsQueued = NULL, listJobsRunning = NULL, array.var = NA_character_, store.job.collection = TRUE, store.job.files = FALSE, scheduler.latency = 0, fs.latency = 0, hooks = list())) #> - tweaked: TRUE #> - call: plan(batchtools_custom, cluster.functions = cf)
#> [1] 1
## Create explicit future f <- future({ cat("PID:", Sys.getpid(), "\n") 42L }) print(f)
#> BatchtoolsFuture: #> Label: ‘<none>’ #> Expression: #> { #> cat("PID:", Sys.getpid(), "\n") #> 42L #> } #> Lazy evaluation: FALSE #> Asynchronous evaluation: TRUE #> Local evaluation: TRUE #> Environment: 0x55f5c1809488 #> Capture standard output: TRUE #> Capture condition classes: ‘condition’ (excluding ‘nothing’) #> Globals: <none> #> Packages: <none> #> L'Ecuyer-CMRG RNG seed: <none> (seed = FALSE) #> Resolved: TRUE #> Value: <not collected> #> Conditions captured: <none> #> Early signaling: FALSE #> Owner process: 48f0146f-9a78-bc98-98bf-83a8683cfb4c #> Class: ‘BatchtoolsFuture’, ‘Future’, ‘environment’ #> batchtools cluster functions: ‘Interactive’ #> batchtools status: ‘defined’, ‘finished’, ‘started’, ‘submitted’ #> batchtools Registry: #> File dir exists: TRUE #> Work dir exists: TRUE #> Job Registry #> Backend : Interactive #> File dir : /tmp/hb/RtmpkgLPfp/future.batchtools/docs/reference/.future/20210519_180005-bp3ZiQ/batchtools_346871191 #> Work dir : /tmp/hb/RtmpkgLPfp/future.batchtools/docs/reference #> Jobs : 1 #> Seed : 19686 #> Writeable: TRUE
v <- value(f)
#> PID: 17536
print(v)
#> [1] 42
options(error = NULL) ## Create explicit future f <- future({ cat("PID:", Sys.getpid(), "\n") 42L }) print(f)
#> BatchtoolsFuture: #> Label: ‘<none>’ #> Expression: #> { #> cat("PID:", Sys.getpid(), "\n") #> 42L #> } #> Lazy evaluation: FALSE #> Asynchronous evaluation: TRUE #> Local evaluation: TRUE #> Environment: 0x55f5c1809488 #> Capture standard output: TRUE #> Capture condition classes: ‘condition’ (excluding ‘nothing’) #> Globals: <none> #> Packages: <none> #> L'Ecuyer-CMRG RNG seed: <none> (seed = FALSE) #> Resolved: TRUE #> Value: <not collected> #> Conditions captured: <none> #> Early signaling: FALSE #> Owner process: 48f0146f-9a78-bc98-98bf-83a8683cfb4c #> Class: ‘BatchtoolsFuture’, ‘Future’, ‘environment’ #> batchtools cluster functions: ‘Interactive’ #> batchtools status: ‘defined’, ‘finished’, ‘started’, ‘submitted’ #> batchtools Registry: #> File dir exists: TRUE #> Work dir exists: TRUE #> Job Registry #> Backend : Interactive #> File dir : /tmp/hb/RtmpkgLPfp/future.batchtools/docs/reference/.future/20210519_180005-bp3ZiQ/batchtools_1608854729 #> Work dir : /tmp/hb/RtmpkgLPfp/future.batchtools/docs/reference #> Jobs : 1 #> Seed : 1122 #> Writeable: TRUE
v <- value(f)
#> PID: 17569
print(v)
#> [1] 42
## Create explicit future f <- future({ cat("PID:", Sys.getpid(), "\n") 42L }) v <- value(f)
#> PID: 17614
print(v)
#> [1] 42