Skip to contents

ProgressTrackingContext

Source: R/ProgressTrackingContext.R
ProgressTrackingContext.Rd

This class represents a progress tracking context for interacting with Backend implementations via the BackendService interface.

Details

This class extends the base Context class and overrides the sapply parent method to decorate the backend instance with additional functionality. Specifically, this class creates a temporary file to log the progress of backend tasks, and then creates a progress bar to display the progress of the backend tasks.

The progress bar is updated after each backend task execution. The timeout between subsequent checks of the temporary log file is controlled by the Options class and defaults to 0.001. This value can be adjusted via the Options instance present in the session base::.Options list (i.e., see set_option()). For example, to set the timeout to 0.1 we can run set_option("progress_timeout", 0.1).

This class is a good example of how to extend the base Context class to decorate the backend instance with additional functionality.

See also

Context, BackendService, Backend, and AsyncBackend.

Super classes

parabar::BackendService -> parabar::Context -> ProgressTrackingContext

Active bindings

bar

The Bar instance registered with the context.

Methods

Public methods

Inherited methods

Method set_backend()

Set the backend instance to be used by the context.

Usage

ProgressTrackingContext$set_backend(backend)

Arguments

backend

An object of class Backend that supports progress tracking implements the BackendService interface.

Details

This method overrides the parent method to validate the backend provided and guarantee it is an instance of the AsyncBackend class.

Method set_bar()

Set the Bar instance to be used by the context.

Usage

ProgressTrackingContext$set_bar(bar)

Arguments

bar

An object of class Bar.

Method configure_bar()

Configure the Bar instance registered with the context.

Usage

ProgressTrackingContext$configure_bar(...)

Arguments

...

A list of named arguments passed to the create() method of the Bar instance. See the documentation of the specific concrete bar for details (e.g., ModernBar).

Method sapply()

Run a task on the backend akin to parallel::parSapply(), but with a progress bar.

Usage

ProgressTrackingContext$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(), but with a progress bar.

Usage

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

ProgressTrackingContext$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 clone()

The objects of this class are cloneable with this method.

Usage

ProgressTrackingContext$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.15)

    # 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 backend instance that does not support progress tracking.
backend <- backend_factory$get("sync")

# Create a progress tracking context object.
context <- ProgressTrackingContext$new()

# Attempt to set the incompatible backend instance.
try(context$set_backend(backend))
#> Error : Argument of type 'SyncBackend' is not assignable to parameter of type 'AsyncBackend'.

# Get a backend instance that does support progress tracking.
backend <- backend_factory$get("async")

# 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)

# Create a bar factory.
bar_factory <- BarFactory$new()

# Get a modern bar instance.
bar <- bar_factory$get("modern")

# Register the bar with the context.
context$set_bar(bar)

# Configure the bar.
context$configure_bar(
    show_after = 0,
    format = " > completed :current out of :total tasks [:percent] [:elapsed]"
)

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

# Get the task output.
backend$get_output(wait = TRUE)
#>  [1] 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35

# Change the bar type.
bar <- bar_factory$get("basic")

# Register the bar with the context.
context$set_bar(bar)

# Remove the previous bar configuration.
context$configure_bar()

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

# Get the task output.
backend$get_output(wait = TRUE)
#>  [1] 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35

# Close the backend.
context$stop()