Create explicit task — task_create

Create an explicit task. Explicit tasks are the simplest sort of task in hipercow and do nothing magic. They accept an R expression (from quote or friends) and possibly a set of variables to export from the global environment. This can then be run on a cluster by loading your variables and running your expression. If your expression depends on packages being attached then you should pass a vector of package names too. This function may disappear, and is used by us to think about the package, it's not designed to really be used.

Usage

task_create_explicit(
  expr,
  export = NULL,
  envir = parent.frame(),
  environment = "default",
  driver = NULL,
  resources = NULL,
  envvars = NULL,
  parallel = NULL,
  root = NULL
)

Arguments

expr: Unevaluated expression object, e.g., from quote
export: Optional character vector of names of objects to export into the evaluating environment
envir: Local R environment in which to find variables for export. The default is the parent frame, which will often do the right thing. Another sensible choice is .GlobalEnv to use the global environment.
environment: Name of the hipercow environment to evaluate the task within.
driver: Name of the driver to use to submit the task. The default (NULL) depends on your configured drivers; if you have no drivers configured no submission happens (or indeed is possible). If you have exactly one driver configured we'll submit your task with it. If you have more than one driver configured, then we will error, though in future versions we may fall back on a default driver if you have one configured. If you pass FALSE here, submission is prevented even if you have no driver configured.
resources: A list generated by hipercow_resources giving the cluster resource requirements to run your task.
envvars: Environment variables as generated by hipercow_envvars, which you might use to control your task. These will be combined with the default environment variables (see vignettes("details"), this can be overridden by the option hipercow.default_envvars), and any driver-specific environment variables (see vignette("windows")). Variables provided here have the highest precedence. You can unset an environment variable by setting it to NA.
parallel: Parallel configuration as generated by hipercow_parallel, which defines which method, if any, will be used to initialise your task for parallel execution.
root: A hipercow root, or path to it. If NULL we search up your directory tree.

Value

A task id, a string of hex characters. Use this to interact with the task.

Examples

cleanup <- hipercow_example_helper()
#> ℹ This example uses a special helper

# About the most simple task that can be created:
id <- task_create_explicit(quote(sqrt(2)))
#> ✔ Submitted task '851c30cf58c5463d69592c7ec1969a21' using 'example'
task_wait(id)
#> [1] TRUE
task_result(id)
#> [1] 1.414214

# Variables are not automatically included with the expression:
a <- 5
id <- task_create_explicit(quote(sqrt(a)))
#> ✔ Submitted task '4959b9c20d12e5a471bf5e145c14cbed' using 'example'
task_info(id)
#> 
#> ── task 4959b9c20d12e5a471bf5e145c14cbed (submitted) ───────────────────────────
#> ℹ Submitted with 'example'
#> ℹ Task type: explicit
#>   • Expression: sqrt(a)
#>   • Locals: (none)
#>   • Environment: default
#>     R_GC_MEM_GROW: 3
#> ℹ Created at 2024-10-08 15:27:07.843662 (moments ago)
#> ! Not started yet (waiting for 50ms)
#> ! Not finished yet (waiting to start)
task_wait(id)
#> [1] FALSE
task_result(id)
#> <simpleError in eval(data$expr, envir): object 'a' not found>

# Include variables by passing them via 'export':
id <- task_create_explicit(quote(sqrt(a)), export = "a")
#> ✔ Submitted task '887b815cd9e41ad67c35e6430045f703' using 'example'
task_info(id)
#> 
#> ── task 887b815cd9e41ad67c35e6430045f703 (submitted) ───────────────────────────
#> ℹ Submitted with 'example'
#> ℹ Task type: explicit
#>   • Expression: sqrt(a)
#>   • Locals: a
#>   • Environment: default
#>     R_GC_MEM_GROW: 3
#> ℹ Created at 2024-10-08 15:27:08.906005 (moments ago)
#> ! Not started yet (waiting for 42ms)
#> ! Not finished yet (waiting to start)
task_wait(id)
#> [1] TRUE
task_result(id)
#> [1] 2.236068

cleanup()
#> ℹ Cleaning up example