A Background Process

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.

reason

Why the Worker was stopped.

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.

Methods

Public methods

• Worker$new()

• Worker$print()

• Worker$start()

• Worker$stop()

• Worker$restart()

• Worker$on()

• Worker$wait()

• Worker$run()

---

Method new()

Creates a background R process for running Jobs.

Usage

Worker$new(globals = NULL, packages = NULL, init = NULL, hooks = NULL)

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.

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. 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').

Returns

A Worker object.

---

Method print()

Print method for a Worker.

Usage

Worker$print(...)

Arguments

...

Arguments are not used currently.

Returns

The Worker, invisibly.

---

Method start()

Restarts a stopped Worker.

Usage

Worker$start()

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$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$restart(reason = "restarting worker")

Arguments

reason

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$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$wait(state = "idle")

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.

Returns

This Worker, invisibly.

---

Method run()

Assigns a Job to this Worker for evaluation on the background process. Worker must be in the 'idle' state.

Usage

Worker$run(job)

Arguments

job

A Job object, as created by Job$new().

Returns

This Worker, invisibly.