worker_class {jobqueue}R Documentation

A Background Process (R6 Class)

Description

Where job expressions are evaluated.

Active bindings

hooks

A named list of currently registered callback hooks.

job

The currently running job.

ps

The ps::ps_handle() object for the background process.

state

The worker's state: 'starting', 'idle', 'busy', or 'stopped'.

uid

A short string, e.g. 'W11', that uniquely identifies this worker.

tmp

The worker's temporary directory.

cnd

The error that caused the worker to stop.

Methods

Public methods


Method new()

Creates a background R process for running jobs.

Usage
worker_class$new(
  globals = NULL,
  packages = NULL,
  namespace = NULL,
  init = NULL,
  hooks = NULL,
  wait = TRUE,
  timeout = Inf
)
Arguments
globals

A named list of variables that all ⁠<job>$expr⁠s will have access to. Alternatively, an object that can be coerced to a named list with as.list(), e.g. named vector, data.frame, or environment.

packages

Character vector of package names to load on workers.

namespace

The name of a package to attach to the worker's environment.

init

A call or R expression wrapped in curly braces to evaluate on each worker just once, immediately after start-up. Will have access to variables defined by globals and assets from packages and namespace. Returned value is ignored.

hooks

A named list of functions to run when the worker state changes, of the form hooks = list(idle = function (worker) {...}). Names of worker hooks are typically starting, idle, busy, stopped, or '*' (duplicates okay). See vignette('hooks').

wait

If TRUE, blocks until the worker is 'idle'. If FALSE, the worker object is returned in the 'starting' state.

timeout

How long to wait for the worker to finish starting (in seconds). If NA, defaults to the worker_class$new() argument.

Returns

A worker object.


Method print()

Print method for a worker.

Usage
worker_class$print(...)
Arguments
...

Arguments are not used currently.

Returns

The worker, invisibly.


Method start()

Restarts a stopped worker.

Usage
worker_class$start(wait = TRUE, timeout = NA)
Arguments
wait

If TRUE, blocks until the worker is 'idle'. If FALSE, the worker object is returned in the 'starting' state.

timeout

How long to wait for the worker to finish starting (in seconds). If NA, defaults to the worker_class$new() argument.

Returns

The worker, invisibly.


Method stop()

Stops a worker by terminating the background process and calling ⁠<job>$stop(reason)⁠ on any jobs currently assigned to this worker.

Usage
worker_class$stop(reason = "worker stopped by user", cls = NULL)
Arguments
reason

Passed to ⁠<job>$stop()⁠ for any jobs currently managed by this worker.

cls

Passed to ⁠<job>$stop()⁠ for any jobs currently managed by this worker.

Returns

The worker, invisibly.


Method restart()

Restarts a worker by calling ⁠<worker>$stop(reason)⁠ and ⁠<worker>$start()⁠ in succession.

Usage
worker_class$restart(
  wait = TRUE,
  timeout = NA,
  reason = "restarting worker",
  cls = NULL
)
Arguments
wait

If TRUE, blocks until the worker is 'idle'. If FALSE, the worker object is returned in the 'starting' state.

timeout

How long to wait for the worker to finish starting (in seconds). If NA, defaults to the worker_class$new() argument.

reason

Passed to ⁠<job>$stop()⁠ for any jobs currently managed by this worker.

cls

Passed to ⁠<job>$stop()⁠ for any jobs currently managed by this worker.

Returns

The worker, invisibly.


Method on()

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

Usage
worker_class$on(state, func)
Arguments
state

The name of a worker state. Typically one of:

  • '*' - Every time the state changes.

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

  • 'starting' - Waiting for the background process to load.

  • 'idle' - Waiting for jobs to be ⁠$run()⁠.

  • 'busy' - While a job is running.

  • 'stopped' - After ⁠<worker>$stop()⁠ is called.

func

A function that accepts a worker object as input. You can call ⁠<worker>$stop()⁠ and other ⁠<worker>$⁠ methods.

Returns

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


Method wait()

Blocks until the worker enters the given state.

Usage
worker_class$wait(state = "idle", timeout = Inf, signal = TRUE)
Arguments
state

The name of a worker state. Typically one of:

  • '*' - Every time the state changes.

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

  • 'starting' - Waiting for the background process to load.

  • 'idle' - Waiting for jobs to be ⁠$run()⁠.

  • 'busy' - While a job is running.

  • 'stopped' - After ⁠<worker>$stop()⁠ is called.

timeout

Stop the worker if it takes longer than this number of seconds.

signal

Raise an error if encountered (will also be recorded in ⁠<worker>$cnd⁠).

Returns

This worker, invisibly.


Method run()

Assigns a job to this worker for evaluation on the background process.

Usage
worker_class$run(job)
Arguments
job

A job object, as created by job_class$new().

Returns

This worker, invisibly.


[Package jobqueue version 1.7.0 Index]