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 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 = FALSE)
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 FALSE
#>  $ 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 (..., 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 = FALSE, store.job.files = FALSE, scheduler.latency = 0, fs.latency = 0, hooks = list()), workers = "<NULL>", envir = parent.frame())
#> - tweaked: TRUE
#> - call: plan(batchtools_custom, cluster.functions = cf)
print(nbrOfWorkers())
#> [1] 1

## Create explicit future
f <- future({
  cat("PID:", Sys.getpid(), "\n")
  42L
})
#> [18:23:16.860] Launched future #1
print(f)
#> BatchtoolsCustomFuture:
#> Label: <unnamed-2>
#> Expression:
#> {
#>     cat("PID:", Sys.getpid(), "\n")
#>     42L
#> }
#> Globals: <none>
#> Packages: <none>
#> L'Ecuyer-CMRG RNG seed: <none> (seed = FALSE)
#> Capture standard output: TRUE
#> Capture condition classes: ‘condition’ (excluding ‘<none>’)
#> Immediate condition classes: ‘immediateCondition’
#> Lazy evaluation: FALSE
#> Local evaluation: TRUE
#> Asynchronous evaluation: TRUE
#> Early signaling: FALSE
#> Environment: 0x55f0f4a7ff70
#> State: ‘running’
#> Resolved: TRUE
#> Unique identifier: deeedcbb59cd4061fe292149b648fa39-2
#> Owner process: deeedcbb59cd4061fe292149b648fa39
#> Class: ‘BatchtoolsCustomFuture’, ‘BatchtoolsFuture’, ‘Future’, ‘environment’
#> Value: <not collected>
#> Conditions captured: <none>
#> batchtools configuration file: <NA>
#> batchtools cluster functions: ‘Interactive’
#> batchtools cluster functions template: <NA>
#> batchtools status: ‘defined’, ‘finished’, ‘started’, ‘submitted’
#> batchtools Registry:
#>   File dir exists: TRUE
#>   Work dir exists: TRUE
#> Job Registry
#>   Backend  : Interactive
#>   File dir : /project-root/projects/prism-pkgdocs-build/installed-pkgs/future.batchtools_0.12.2/docs/reference/.future/20250701_182316-vvDbHa/batchtools_1782273127
#>   Work dir : /project-root/projects/prism-pkgdocs-build/installed-pkgs/future.batchtools_0.12.2/docs/reference
#>   Jobs     : 1
#>   Seed     : 12335
#>   Writeable: TRUE
v <- value(f)
#> PID: 2042908 
print(v)
#> [1] 42

options(error = NULL)


## Create explicit future
f <- future({
  cat("PID:", Sys.getpid(), "\n")
  42L
})
#> [18:23:17.117] Launched future #1
print(f)
#> BatchtoolsCustomFuture:
#> Label: <unnamed-4>
#> Expression:
#> {
#>     cat("PID:", Sys.getpid(), "\n")
#>     42L
#> }
#> Globals: <none>
#> Packages: <none>
#> L'Ecuyer-CMRG RNG seed: <none> (seed = FALSE)
#> Capture standard output: TRUE
#> Capture condition classes: ‘condition’ (excluding ‘<none>’)
#> Immediate condition classes: ‘immediateCondition’
#> Lazy evaluation: FALSE
#> Local evaluation: TRUE
#> Asynchronous evaluation: TRUE
#> Early signaling: FALSE
#> Environment: 0x55f0f4a7ff70
#> State: ‘running’
#> Resolved: TRUE
#> Unique identifier: deeedcbb59cd4061fe292149b648fa39-4
#> Owner process: deeedcbb59cd4061fe292149b648fa39
#> Class: ‘BatchtoolsCustomFuture’, ‘BatchtoolsFuture’, ‘Future’, ‘environment’
#> Value: <not collected>
#> Conditions captured: <none>
#> batchtools configuration file: <NA>
#> batchtools cluster functions: ‘Interactive’
#> batchtools cluster functions template: <NA>
#> batchtools status: ‘defined’, ‘finished’, ‘started’, ‘submitted’
#> batchtools Registry:
#>   File dir exists: TRUE
#>   Work dir exists: TRUE
#> Job Registry
#>   Backend  : Interactive
#>   File dir : /project-root/projects/prism-pkgdocs-build/installed-pkgs/future.batchtools_0.12.2/docs/reference/.future/20250701_182316-vvDbHa/batchtools_795675940
#>   Work dir : /project-root/projects/prism-pkgdocs-build/installed-pkgs/future.batchtools_0.12.2/docs/reference
#>   Jobs     : 1
#>   Seed     : 27606
#>   Writeable: TRUE
v <- value(f)
#> PID: 2042908 
print(v)
#> [1] 42



## Create explicit future
f <- future({
  cat("PID:", Sys.getpid(), "\n")
  42L
})
#> [18:23:17.237] Launched future #1
v <- value(f)
#> PID: 2042908 
print(v)
#> [1] 42