Skip to contents

SyncBackend

Source: R/SyncBackend.R
SyncBackend.Rd

This is a concrete implementation of the abstract class Backend that implements the Service interface. This backend executes tasks in parallel on a parallel::makeCluster() cluster synchronously (i.e., blocking the main R session).

See also

Service, Backend, AsyncBackend, and Context.

Super classes

parabar::Service -> parabar::Backend -> SyncBackend

Methods

Public methods

Method new()

Create a new SyncBackend object.

Usage

SyncBackend$new()

Returns

An object of class SyncBackend.

Method finalize()

Destroy the current SyncBackend instance.

Usage

SyncBackend$finalize()

Returns

An object of class SyncBackend.

Method start()

Start the backend.

Usage

SyncBackend$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

SyncBackend$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

SyncBackend$clear()

Returns

This method returns void.

Method peek()

Inspect the backend for variables available in the .GlobalEnv.

Usage

SyncBackend$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

SyncBackend$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

SyncBackend$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

SyncBackend$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

SyncBackend$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

SyncBackend$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

SyncBackend$get_output(...)

Arguments

...

Additional arguments currently not in use.

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 will return NULL. 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

SyncBackend$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

# 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 synchronous backend object.
backend <- SyncBackend$new()

# Start the cluster on the backend.
backend$start(specification)

# Check if there is anything on the backend.
backend$peek()
#> [[1]]
#> character(0)
#> 
#> [[2]]
#> character(0)
#> 

# Create a dummy variable.
name <- "parabar"

# Export the variable from the current environment to the backend.
backend$export("name", environment())

# Remove variable from current environment.
rm(name)

# Run an expression on the backend, using the exported variable `name`.
backend$evaluate({
    # Print the name.
    print(paste0("Hello, ", name, "!"))
})
#> [[1]]
#> [1] "Hello, parabar!"
#> 
#> [[2]]
#> [1] "Hello, parabar!"
#> 

# Run a task in parallel (i.e., approx. 1.25 seconds).
backend$sapply(
    x = 1:10,
    fun = function(x) {
        # Sleep a bit.
        Sys.sleep(0.25)

        # Compute something.
        output <- x + 1

        # Return the result.
        return(output)
    }
)

# Get the task output.
backend$get_output()
#>  [1]  2  3  4  5  6  7  8  9 10 11

# Clear the backend.
backend$clear()

# Check that there is nothing on the cluster.
backend$peek()
#> [[1]]
#> character(0)
#> 
#> [[2]]
#> character(0)
#> 

# Stop the backend.
backend$stop()

# Check that the backend is not active.
backend$active
#> [1] FALSE