job {job}

Run Code as an RStudio Job

Description

See examples for an introduction. See the job website for more examples. See details for some warnings. Note that job::empty()is identical to job::job() but all arguments default to NULL.

Usage

job(
  ...,
  import = "all",
  packages = .packages(),
  opts = options(),
  title = NULL
)

empty(..., import = NULL, packages = NULL, opts = NULL, title = NULL)

Arguments

...

A named or unnamed code block enclosed in curly brackets, {}. Named code blocks will assign the that name in globalenv(). Unnamed code blocks will assign job variables directly to globalenv() upon completion. Control what gets returned using export within the code block.

import

Which objects to import into the job.

• "all": Import all objects.

• "auto" (default): Detect which objects are used in the code and import those.

• c(foo, bar, ...): A vector of unquoted variables to import into the job.

• c("foo", "bar", ...): A vector of quoted variables to import into the job.

• NULL: import nothing.

packages

Character vector of packages to load in the job. Defaults to all loaded packages in the calling environment. NULL loads only default packages. You can combine packages = NULL with writing library(my_package) in the code block.

opts

List of options to overwrite in the job. Defaults to options(), i.e., copy all options to the job. NULL uses defaults.

title

The job title. You can write e.g., "Cross-Validation: {code}" to include a code snippet in the title. If title = NULL (default), the name of the code chunk is used. If ... is unnamed, the code is shown.

Details

This is a wrapper around rstudioapi::jobRunScript. To control what gets returned, see export. By default, all objects that changed during the job are returned, i.e., job::export("changed").

• Returning large objects:jobRunScript is very slow at importing and exporting large objects. For exporting back into globalenv(), it may be faster to saveRDS() results within the job and readRDS() them in your environment.

Value

Invisibly returns the job id on which you can call other ⁠rstudioapi::job*⁠ functions, e.g., ⁠rstudioapi::rstudioapi::jobRemove(job_id)⁠.

Functions

• empty(): job::job() but with NULL defaults, i.e., an "empty" job.

Author(s)

Jonas Kristoffer Lindeløv, [e-mail]

See Also

export, jobRunScript

Examples

if (rstudioapi::isAvailable()) {
  # Unnamed code chunks returns to globalenv()
  global_var = 5
  job::job({
    x = rnorm(global_var)
    print("This text goes to the job console")
    m = mean(x)
  })

  # later:
  print(x)
  print(m)


  # Named code chunks assign job environment to that name
  job::job(my_result = {
    y = rnorm(global_var)
    sigma = sd(y)
  }, title = "Title with code: {code}")

  # later:
  print(my_result$y)
  print(my_result$sigma)


  # Delete everything in the job environment to return nothing.
  # Useful if text output + file output is primary
  job::job({
    some_cars = mtcars[mtcars$cyl > 4, ]
    print(mean(some_cars$mpg))
    print(summary(some_cars))
    # saveRDS(some_cars, "job_result.rds")

    job::export("none")  # return nothing
  })


  # Control imports from calling environment (variables, packages, options)
  my_df = data.frame(names = c("alice", "bob"))
  ignore_var = 15
  job::job(result2 = {
    if (exists("ignore_var") == FALSE)
      print("ignore_var is not set here")

    names = rep(my_df$names, global_var)
  }, import = c(global_var, my_df), packages = NULL, opts = list(mc.cores = 3))

  # later
  print(result2$names)
}