job_class: Define an R Expression (R6 Class)
In jobqueue: Run Interruptible Code Asynchronously
job_class R Documentation
Define an R Expression (R6 Class)
Description
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>$state will trigger callback hooks.
outputGet or set - job's raw output.
Assigning to <job>$output will change the job's state
to 'done'.
jobqueueThe jobqueue 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_doneTRUE or FALSE depending on if the job's result is
ready.
uidA 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
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's globals,
packages, and init configuration. See vignette('eval').
varsA 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.
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). See vignette('stops').
hooksA 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').
reformatSet reformat = function (job) to define what
<job>$result should return. The default, reformat = NULL passes
<job>$output to <job>$result unchanged.
See vignette('results').
signalShould 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').
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
<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
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' - 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.
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>$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
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' - 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.
timeoutStop 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
reasonA message to include in the 'interrupt' condition object that
will be returned as the job's result. Or a condition
object.
clsCharacter vector of additional classes to prepend to
c('interrupt', 'condition').
Returns
This job, invisibly.
jobqueue documentation built on June 8, 2025, 12:45 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| job_class | R Documentation |
Define an R Expression (R6 Class)
Description
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 -
jobto proxy in place of runningexpr.stateGet or set - The
job'sstate:'created','submitted','queued','dispatched','starting','running', or'done'. Assigning to<job>$statewill trigger callback hooks.outputGet or set -
job'sraw output. Assigning to<job>$outputwill change thejob'sstate to'done'.jobqueueThe
jobqueuethat thisjobbelongs to.workerThe
workerthat thisjobbelongs to.resultResult of
expr. Will block untiljobis finished.hooksCurrently registered callback hooks as a named list of functions. Set new hooks with
<job>$on().is_doneTRUEorFALSEdepending on if thejob'sresult is ready.uidA short string, e.g.
'J16', that uniquely identifies thisjob.
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
exprA 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'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
jobpasses 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').hooksA named list of functions to run when the
jobstate changes, of the formhooks = list(created = function (worker) {...}). Or afunction (job)that returns the same. Names ofworkerhooks 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 afunction (job)that returns the same. Used to limit the number ofjobsrunning simultaneously to respect<jobqueue>$max_cpus. Does not prevent ajobfrom using more CPUs than reserved....Arbitrary named values to add to the returned
jobobject.
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
stateThe name of a
jobstate. 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>$jobqueueis 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
jobobject as input. You can call<job>$stop()or edit<job>$values and the changes will be persisted (sincejobsare reference class objects). You can also edit/stop other queuedjobsby modifying thejobsin<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
stateThe name of a
jobstate. 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>$jobqueueis 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
jobif it takes longer than this number of seconds, orNULL.
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
reasonA message to include in the 'interrupt' condition object that will be returned as the
job'sresult. Or a condition object.clsCharacter vector of additional classes to prepend to
c('interrupt', 'condition').
Returns
This job, invisibly.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.