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 runningexpr
.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 thejob's
state to'done'
.jobqueue
The
jobqueue
that thisjob
belongs to.worker
The
worker
that thisjob
belongs to.result
Result of
expr
. Will block untiljob
is finished.hooks
Currently registered callback hooks as a named list of functions. Set new hooks with
<job>$on()
.is_done
TRUE
orFALSE
depending on if thejob's
result is ready.uid
A short string, e.g.
'J16'
, that uniquely identifies thisjob
.
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 byvars
, as well as theworker's
globals
,packages
, andinit
configuration. Seevignette('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 withas.list()
, e.g. named vector, data.frame, or environment. Or afunction (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 afunction (job)
that returns the same. Example:timeout = c(total = 2.5, running = 1)
. Seevignette('stops')
.hooks
A named list of functions to run when the
job
state changes, of the formhooks = list(created = function (worker) {...})
. Or afunction (job)
that returns the same. Names ofworker
hooks are typically'created'
,'submitted'
,'queued'
,'dispatched'
,'starting'
,'running'
,'done'
, or'*'
(duplicates okay). Seevignette('hooks')
.reformat
Set
reformat = function (job)
to define what<job>$result
should return. The default,reformat = NULL
passes<job>$output
to<job>$result
unchanged. Seevignette('results')
.signal
Should calling
<job>$result
signal on condition objects? WhenFALSE
,<job>$result
will return the object without taking additional action. Setting toTRUE
or 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 returnsTRUE
orFALSE
. Seevignette('results')
.cpus
How many CPU cores to reserve for this
job
. Or afunction (job)
that returns the same. Used to limit the number ofjobs
running simultaneously to respect<jobqueue>$max_cpus
. Does not prevent ajob
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
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'
- Afterjob_class$new()
initialization.'submitted'
- After<job>$jobqueue
is assigned.'queued'
- Afterstop_id
andcopy_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 (sincejobs
are reference class objects). You can also edit/stop other queuedjobs
by modifying thejobs
in<job>$jobqueue$jobs
. Return value is ignored.
Method wait()
Blocks until the job
enters the given state.
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'
- Afterjob_class$new()
initialization.'submitted'
- After<job>$jobqueue
is assigned.'queued'
- Afterstop_id
andcopy_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, orNULL
.
Method stop()
Stop this job
. If the job
is running, its
worker
will be restarted.