Define a Job to Run on a Background Worker Process.
Define a Job to Run on a Background Worker Process.
Active bindings
exprGet the expression that will be run by this Job.
varsGet or set the variables that will be placed into the expression's environment before evaluation.
reformatGet or set the
function (job, output)for transforming rawcallroutput to the Job's result.cpusGet or set the number of CPUs to reserve for evaluating
expr.tmaxGet or set the time limits to apply to this Job.
proxyGet or set the Job to proxy in place of running
expr.stateGet or set the Job's state (setting will trigger callbacks).
outputGet or set the Job's raw
callroutput (setting will change the Job's state to 'done').resultGet the result of
expr. Will block until Job is finished.hooksGet all currently registered callback hooks - a named list of functions.
is_doneReturns TRUE or FALSE depending on if the Job's result is ready.
uidReturns a 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.
Usage
Job$new(
expr,
vars = NULL,
tmax = NULL,
hooks = NULL,
reformat = TRUE,
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.varsA list of named variables to make available to
exprduring evaluation.tmaxA 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'. Example:
tmax = c(total = 2.5, running = 1)will force-stop a job 2.5 seconds after it is submitted, and also limits its time in the running state to just 1 second.hooksA list of functions to run when the Job state changes, of the form
hooks = list(created = function (job) {...}, done = ~{...}). The names of these functions should becreated,submitted,queued,dispatched,starting,running,done, or'*'.'*'will be run every time the state changes, whereas the others will only be run when the Job enters that state. Duplicate names are allowed.reformatThe underlying call to
callr::r_session$call()returns information on stdout, stderr, etc. Whenreformat=TRUE(the default), only the result of the expression is returned. Setreformat=FALSEto return the entire callr output, orreformat=function(job,output)to use a function of your own to post-process the output from callr.cpusHow many CPU cores to reserve for this Job. The Queue uses this number to limit the number of simultaneously running Jobs; it does not prevent a Job from using more CPUs than reserved.
Method print()
Print method for a Job.
Method on()
Attach a callback function.
Arguments
stateThe Job state that will trigger this function. Typically one of:
'*'-Every time the state changes.
'.next'-Only one time, the next time the state changes.
'created'-After
Job$new()initialization.'submitted'-Before
stop_idandcopy_idare resolved.'queued'-After
<Job>$queueis assigned.'dispatched'-After
<Job>$workeris assigned.'starting'-Before evaluation begins.
'running'-After evaluation begins.
'done'-After
<Job>$outputis assigned.
funcA function that accepts a Job object as input. You can call
<Job>$stop()or edit its 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 stop()
Stop this Job. If the Job is running, the worker process will be rebooted.