The Job object encapsulates an expression and its evaluation parameters. It also provides a way to check for and retrieve the result.
Active bindings
exprR expression that will be run by this Job.
varsGet or set - List of variables that will be placed into the expression's environment before evaluation.
reformatGet or set -
function (job)for defining<Job>$result.signalGet or set - Conditions to signal.
cpusGet or set - Number of CPUs to reserve for evaluating
expr.timeoutGet or set - Time limits to apply to this Job.
proxyGet or set - Job to proxy in place of running
expr.stateGet or set - The Job's state:
'created','submitted','queued','dispatched','starting','running', or'done'. Assigning to<Job>$statewill trigger callback hooks.outputGet or set - Job's raw output. Assigning to
<Job>$outputwill change the Job's state to'done'.queueThe Queue that this Job belongs to.
workerThe Worker that this Job belongs to.
resultResult of
expr. Will block until Job is finished.hooksCurrently registered callback hooks as a named list of functions. Set new hooks with
<Job>$on().is_doneTRUEorFALSEdepending on if the Job's result is ready.uidA short string, e.g.
'J16', that uniquely identifies this Job.
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$new(). Instead, create a Queue and use
<Queue>$run() to generate Job objects.
Usage
Job$new(
expr,
vars = NULL,
timeout = NULL,
hooks = NULL,
reformat = NULL,
signal = FALSE,
cpus = 1L,
...
)Arguments
exprA 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'sglobals,packages, andinitconfiguration. Seevignette('eval').varsA named list of variables to make available to
exprduring evaluation. Alternatively, an object that can be coerced to a named list withas.list(), e.g. named vector, data.frame, or environment. Or afunction (job)that returns such an object.timeoutA 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). Seevignette('stops').hooksA named list of functions to run when the Job state changes, of the form
hooks = list(created = function (worker) {...}). Or afunction (job)that returns the same. Names of worker hooks are typically'created','submitted','queued','dispatched','starting','running','done', or'*'(duplicates okay). Seevignette('hooks').reformatSet
reformat = function (job)to define what<Job>$resultshould return. The default,reformat = NULLpasses<Job>$outputto<Job>$resultunchanged. Seevignette('results').signalShould calling
<Job>$resultsignal on condition objects? WhenFALSE,<Job>$resultwill return the object without taking additional action. Setting toTRUEor a character vector of condition classes, e.g.c('interrupt', 'error', 'warning'), will cause the equivalent ofstop(<condition>)to be called when those conditions are produced. Alternatively, afunction (job)that returnsTRUEorFALSE. Seevignette('results').cpusHow 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<Queue>$max_cpus. Does not prevent a Job from using more CPUs than reserved....Arbitrary named values to add to the returned Job object.
Method print()
Print method for a Job.
Method on()
Attach a callback function to execute when the Job enters state.
Arguments
stateThe name of a Job state. Typically one of:
'*'- Every time the state changes.'.next'- Only one time, the next time the state changes.'created'- AfterJob$new()initialization.'submitted'- After<Job>$queueis assigned.'queued'- Afterstop_idandcopy_idare resolved.'dispatched'- After<Job>$workeris assigned.'starting'- Before evaluation begins.'running'- After evaluation begins.'done'- After<Job>$outputis assigned.
Custom states can also be specified.
funcA 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>$queue$jobs. Return value is ignored.
Method wait()
Blocks until the Job enters the given state.
Arguments
stateThe name of a Job state. Typically one of:
'*'- Every time the state changes.'.next'- Only one time, the next time the state changes.'created'- AfterJob$new()initialization.'submitted'- After<Job>$queueis assigned.'queued'- Afterstop_idandcopy_idare resolved.'dispatched'- After<Job>$workeris assigned.'starting'- Before evaluation begins.'running'- After evaluation begins.'done'- After<Job>$outputis assigned.
Custom states can also be specified.
timeoutStop the Job if it takes longer than this number of seconds, or
NULL.
Method stop()
Stop this Job. If the Job is running, its Worker will be restarted.