Run a Task in Parallel

This function can be used to run a task in parallel. The task is executed in parallel on the specified backend, similar to parallel::parApply(). If backend = NULL, the task is executed sequentially using base::apply(). See the Details section for more information on how this function works.

Usage

par_apply(backend = NULL, x, margin, fun, ...)

Arguments

backend

An object of class Backend as returned by the start_backend() function. It can also be NULL to run the task sequentially via base::apply(). The default value is NULL.

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.

Value

The dimensions of the output vary according to the margin argument. Consult the documentation of base::apply() for a detailed explanation on how the output is structured.

Details

This function uses the UserApiConsumer class that acts like an interface for the developer API of the parabar package.

See also

start_backend(), peek(), export(), evaluate(), clear(), configure_bar(), par_sapply(), par_lapply(), stop_backend(), set_option(), get_option(), Options, UserApiConsumer, and Service.

Examples

# \donttest{

# Define a simple task.
task <- function(x) {
    # Perform computations.
    Sys.sleep(0.01)

    # Return the result.
    mean(x)
}

# Define a matrix for the task.
x <- matrix(rnorm(100^2, mean = 10, sd = 0.5), nrow = 100, ncol = 100)

# Start an asynchronous backend.
backend <- start_backend(cores = 2, cluster_type = "psock", backend_type = "async")

# Run a task in parallel over the rows of `x`.
results <- par_apply(backend, x = x, margin = 1, fun = task)

# Run a task in parallel over the columns of `x`.
results <- par_apply(backend, x = x, margin = 2, fun = task)

# The task can also be run over all elements of `x` using `margin = c(1, 2)`.
# Improper dimensions will throw an error.
try(par_apply(backend, x = x, margin = c(1, 2, 3), fun = task))
#> Error : Margins {1, 2, 3} not compatible with array dimensions {100, 100}.

# Disable progress tracking.
set_option("progress_track", FALSE)

# Run a task in parallel.
results <- par_apply(backend, x = x, margin = 1, fun = task)

# Enable progress tracking.
set_option("progress_track", TRUE)

# Change the progress bar options.
configure_bar(type = "modern", format = "[:bar] :percent")

# Run a task in parallel.
results <- par_apply(backend, x = x, margin = 1, fun = task)

# Stop the backend.
stop_backend(backend)

# Start a synchronous backend.
backend <- start_backend(cores = 2, cluster_type = "psock", backend_type = "sync")

# Run a task in parallel.
results <- par_apply(backend, x = x, margin = 1, fun = task)
#> Warning: Progress tracking not supported for backend of type 'SyncBackend'.

# Disable progress tracking to remove the warning that progress is not supported.
set_option("progress_track", FALSE)

# Run a task in parallel.
results <- par_apply(backend, x = x, margin = 1, fun = task)

# Stop the backend.
stop_backend(backend)

# Run the task using the `base::lapply` (i.e., non-parallel).
results <- par_apply(NULL, x = x, margin = 1, fun = task)

# }