Context

This class represents the base context for interacting with Backend implementations via the Service interface.

Details

This class is a vanilla wrapper around a Backend implementation. It registers a backend instance and forwards all Service methods calls to the backend instance. Subclasses can override any of the Service methods to decorate the backend instance with additional functionality (e.g., see the ProgressTrackingContext class).

See also

ProgressTrackingContext, Service, Backend, and SyncBackend.

Active bindings

backend

The Backend object registered with the context.

Methods

Public methods

• Context$set_backend()

• Context$start()

• Context$stop()

• Context$clear()

• Context$peek()

• Context$export()

• Context$evaluate()

• Context$sapply()

• Context$lapply()

• Context$apply()

• Context$get_output()

• Context$clone()

---

Method set_backend()

Set the backend instance to be used by the context.

Usage

Context$set_backend(backend)

Arguments

backend

An object of class Backend that implements the Service interface.

---

Method start()

Start the backend.

Usage

Context$start(specification)

Arguments

specification

An object of class Specification that contains the backend configuration.

Returns

This method returns void. The resulting backend must be stored in the .cluster private field on the Backend abstract class, and accessible to any concrete backend implementations via the active binding cluster.

---

Method stop()

Stop the backend.

Usage

Context$stop()

Returns

This method returns void.

---

Method clear()

Remove all objects from the backend. This function is equivalent to calling rm(list = ls(all.names = TRUE)) on each node in the backend.

Usage

Context$clear()

Returns

This method returns void.

---

Method peek()

Inspect the backend for variables available in the .GlobalEnv.

Usage

Context$peek()

Returns

This method returns a list of character vectors, where each element corresponds to a node in the backend. The character vectors contain the names of the variables available in the .GlobalEnv on each node.

---

Method export()

Export variables from a given environment to the backend.

Usage

Context$export(variables, environment)

Arguments

variables

A character vector of variable names to export.

environment

An environment object from which to export the variables. Defaults to the parent frame.

Returns

This method returns void.

---

Method evaluate()

Evaluate an arbitrary expression on the backend.

Usage

Context$evaluate(expression)

Arguments

expression

An unquoted expression to evaluate on the backend.

Returns

This method returns the result of the expression evaluation.

---

Method sapply()

Run a task on the backend akin to parallel::parSapply().

Usage

Context$sapply(x, fun, ...)

Arguments

x

An atomic vector or list to pass to the fun function.

fun

A function to apply to each element of x.

...

Additional arguments to pass to the fun function.

Returns

This method returns void. The output of the task execution must be stored in the private field .output on the Backend abstract class, and is accessible via the get_output() method.

---

Method lapply()

Run a task on the backend akin to parallel::parLapply().

Usage

Context$lapply(x, fun, ...)

Arguments

x

An atomic vector or list to pass to the fun function.

fun

A function to apply to each element of x.

...

Additional arguments to pass to the fun function.

Returns

This method returns void. The output of the task execution must be stored in the private field .output on the Backend abstract class, and is accessible via the get_output() method.

---

Method apply()

Run a task on the backend akin to parallel::parApply().

Usage

Context$apply(x, margin, fun, ...)

Arguments

x

An array to pass to the fun function.

margin

A numeric vector indicating the dimensions of x the fun function should be applied over. For example, for a matrix, margin = 1 indicates applying fun rows-wise, margin = 2 indicates applying fun columns-wise, and margin = c(1, 2) indicates applying fun element-wise. Named dimensions are also possible depending on x. See parallel::parApply() and base::apply() for more details.

fun

A function to apply to x according to the margin.

...

Additional arguments to pass to the fun function.

Returns

This method returns void. The output of the task execution must be stored in the private field .output on the Backend abstract class, and is accessible via the get_output() method.

---

Method get_output()

Get the output of the task execution.

Usage

Context$get_output(...)

Arguments

...

Additional arguments to pass to the backend registered with the context. This is useful for backends that require additional arguments to fetch the output (e.g., AsyncBackend$get_output(wait = TRUE)).

Details

This method fetches the output of the task execution after calling the sapply() method. It returns the output and immediately removes it from the backend. Therefore, subsequent calls to this method are not advised. This method should be called after the execution of a task.

Returns

A vector, matrix, or list of the same length as x, containing the results of the fun. The output format differs based on the specific operation employed. Check out the documentation for the apply operations of parallel::parallel for more information.

---

Method clone()

The objects of this class are cloneable with this method.

Usage

Context$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

# Define a task to run in parallel.
task <- function(x, y) {
    # Sleep a bit.
    Sys.sleep(0.25)

    # Return the result of a computation.
    return(x + y)
}

# Create a specification object.
specification <- Specification$new()

# Set the number of cores.
specification$set_cores(cores = 2)

# Set the cluster type.
specification$set_type(type = "psock")

# Create a backend factory.
backend_factory <- BackendFactory$new()

# Get a synchronous backend instance.
backend <- backend_factory$get("sync")

# Create a base context object.
context <- Context$new()

# Register the backend with the context.
context$set_backend(backend)

# From now all, all backend operations are intercepted by the context.

# Start the backend.
context$start(specification)

# Run a task in parallel (i.e., approx. 1.25 seconds).
context$sapply(x = 1:10, fun = task, y = 10)

# Get the task output.
context$get_output()
#>  [1] 11 12 13 14 15 16 17 18 19 20

# Close the backend.
context$stop()

# Get an asynchronous backend instance.
backend <- backend_factory$get("async")

# Register the backend with the same context object.
context$set_backend(backend)

# Start the backend reusing the specification object.
context$start(specification)

# Run a task in parallel (i.e., approx. 1.25 seconds).
context$sapply(x = 1:10, fun = task, y = 10)

# Get the task output.
backend$get_output(wait = TRUE)
#>  [1] 11 12 13 14 15 16 17 18 19 20

# Close the backend.
context$stop()