Skip to contents

A Background Process (R6 Class)

Source: R/worker_class.r
worker_class.Rd

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>$exprs 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.