Skip to contents

Define an R Expression (R6 Class)

Source: R/job_class.r
job_class.Rd

The job object encapsulates an expression and its evaluation parameters. It also provides a way to check for and retrieve the result.

Active bindings

expr

R expression that will be run by this job.

vars

Get or set - List of variables that will be placed into the expression's environment before evaluation.

reformat

Get or set - function (job) for defining <job>$result.

signal

Get or set - Conditions to signal.

cpus

Get or set - Number of CPUs to reserve for evaluating expr.

timeout

Get or set - Time limits to apply to this job.

proxy

Get or set - job to proxy in place of running expr.

state

Get or set - The job's state: 'created', 'submitted', 'queued', 'dispatched', 'starting', 'running', or 'done'. Assigning to <job>$state will trigger callback hooks.

output

Get or set - job's raw output. Assigning to <job>$output will change the job's state to 'done'.

jobqueue

The jobqueue that this job belongs to.

worker

The worker that this job belongs to.

result

Result of expr. Will block until job is finished.

hooks

Currently registered callback hooks as a named list of functions. Set new hooks with <job>$on().

is_done

TRUE or FALSE depending on if the job's result is ready.

uid

A short string, e.g. 'J16', that uniquely identifies this job.

Methods

Public methods

Method new()

Creates a job object defining how to run an expression on a background worker process.

Typically you won't need to call job_class$new(). Instead, create a jobqueue and use <jobqueue>$run() to generate job objects.

Usage

job_class$new(
  expr,
  vars = NULL,
  timeout = NULL,
  hooks = NULL,
  reformat = NULL,
  signal = FALSE,
  cpus = 1L,
  ...
)

Arguments

expr

A call or R expression wrapped in curly braces to evaluate on a worker. Will have access to any variables defined by vars, as well as the worker's globals, packages, and init configuration. See vignette('eval').

vars

A named list of variables to make available to expr during evaluation. Alternatively, an object that can be coerced to a named list with as.list(), e.g. named vector, data.frame, or environment. Or a function (job) that returns such an object.

timeout

A named numeric vector indicating the maximum number of seconds allowed for each state the job passes through, or 'total' to apply a single timeout from 'submitted' to 'done'. Or a function (job) that returns the same. Example: timeout = c(total = 2.5, running = 1). See vignette('stops').

hooks

A named list of functions to run when the job state changes, of the form hooks = list(created = function (worker) {...}). Or a function (job) that returns the same. Names of worker hooks are typically 'created', 'submitted', 'queued', 'dispatched', 'starting', 'running', 'done', or '*' (duplicates okay). See vignette('hooks').

reformat

Set reformat = function (job) to define what <job>$result should return. The default, reformat = NULL passes <job>$output to <job>$result unchanged. See vignette('results').

signal

Should calling <job>$result signal on condition objects? When FALSE, <job>$result will return the object without taking additional action. Setting to TRUE or a character vector of condition classes, e.g. c('interrupt', 'error', 'warning'), will cause the equivalent of stop(<condition>) to be called when those conditions are produced. Alternatively, a function (job) that returns TRUE or FALSE. See vignette('results').

cpus

How many CPU cores to reserve for this job. Or a function (job) that returns the same. Used to limit the number of jobs running simultaneously to respect <jobqueue>$max_cpus. Does not prevent a job from using more CPUs than reserved.

...

Arbitrary named values to add to the returned job object.

Returns

A job object.

Method print()

Print method for a job.

Usage

job_class$print(...)

Arguments

...

Arguments are not used currently.

Returns

This job, invisibly.

Method on()

Attach a callback function to execute when the job enters state.

Usage

job_class$on(state, func)

Arguments

state

The name of a job state. Typically one of:

  • '*' - Every time the state changes.

  • '.next' - Only one time, the next time the state changes.

  • 'created' - After job_class$new() initialization.

  • 'submitted' - After <job>$jobqueue is assigned.

  • 'queued' - After stop_id and copy_id are resolved.

  • 'dispatched' - After <job>$worker is assigned.

  • 'starting' - Before evaluation begins.

  • 'running' - After evaluation begins.

  • 'done' - After <job>$output is assigned.

Custom states can also be specified.

func

A function that accepts a job object as input. You can call <job>$stop() or edit <job>$ values and the changes will be persisted (since jobs are reference class objects). You can also edit/stop other queued jobs by modifying the jobs in <job>$jobqueue$jobs. Return value is ignored.

Returns

A function that when called removes this callback from the job.

Method wait()

Blocks until the job enters the given state.

Usage

job_class$wait(state = "done", timeout = NULL)

Arguments

state

The name of a job state. Typically one of:

  • '*' - Every time the state changes.

  • '.next' - Only one time, the next time the state changes.

  • 'created' - After job_class$new() initialization.

  • 'submitted' - After <job>$jobqueue is assigned.

  • 'queued' - After stop_id and copy_id are resolved.

  • 'dispatched' - After <job>$worker is assigned.

  • 'starting' - Before evaluation begins.

  • 'running' - After evaluation begins.

  • 'done' - After <job>$output is assigned.

Custom states can also be specified.

timeout

Stop the job if it takes longer than this number of seconds, or NULL.

Returns

This job, invisibly.

Method stop()

Stop this job. If the job is running, its worker will be restarted.

Usage

job_class$stop(reason = "job stopped by user", cls = NULL)

Arguments

reason

A message to include in the 'interrupt' condition object that will be returned as the job's result. Or a condition object.

cls

Character vector of additional classes to prepend to c('interrupt', 'condition').

Returns

This job, invisibly.