Skip to contents

UserApiConsumer

Source: R/UserApiConsumer.R
UserApiConsumer.Rd

This class is an opinionated interface around the developer API of the parabar package. See the Details section for more information on how this class works.

Details

This class acts as a wrapper around the R6::R6 developer API of the parabar package. In a nutshell, it provides an opinionated interface by wrapping the developer API in simple functional calls. More specifically, for executing a task in parallel, this class performs the following steps:

  • Validates the backend provided.

  • Instantiates an appropriate parabar context based on the backend. If the backend supports progress tracking (i.e., the backend is an instance of AsyncBackend), a progress tracking context (i.e., ProgressTrackingContext) is instantiated and used. Otherwise, a regular context (i.e., Context) is instantiated. A regular context is also used if the progress tracking is disabled via the Options instance.

  • Registers the backend with the context.

  • Instantiates and configures the progress bar based on the Options instance in the session base::.Options list.

  • Executes the task in parallel, and displays a progress bar if appropriate.

  • Fetches the results from the backend and returns them.

See also

start_backend(), stop_backend(), configure_bar(), par_sapply(), and par_lapply().

Methods

Public methods

Method sapply()

Execute a task in parallel akin to parallel::parSapply().

Usage

UserApiConsumer$sapply(backend, x, 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::sapply().

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

A vector of the same length as x containing the results of the fun. The output format resembles that of base::sapply().

Method lapply()

Execute a task in parallel akin to parallel::parLapply().

Usage

UserApiConsumer$lapply(backend, x, 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::lapply().

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

A list of the same length as x containing the results of the fun. The output format resembles that of base::lapply().

Method apply()

Execute a task in parallel akin to parallel::parApply().

Usage

UserApiConsumer$apply(backend, 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().

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

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.

Method clone()

The objects of this class are cloneable with this method.

Usage

UserApiConsumer$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

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

    # Return the result.
    return(x + 1)
}

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

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

# Create an user API consumer.
consumer <- UserApiConsumer$new()

# Execute the task using the `sapply` parallel operation.
output_sapply <- consumer$sapply(backend = backend, x = 1:200, fun = task)

# Print the head of the `sapply` operation output.
head(output_sapply)
#> [1] 2 3 4 5 6 7

# Execute the task using the `sapply` parallel operation.
output_lapply <- consumer$lapply(backend = backend, x = 1:200, fun = task)

# Print the head of the `lapply` operation output.
head(output_lapply)
#> [[1]]
#> [1] 2
#> 
#> [[2]]
#> [1] 3
#> 
#> [[3]]
#> [1] 4
#> 
#> [[4]]
#> [1] 5
#> 
#> [[5]]
#> [1] 6
#> 
#> [[6]]
#> [1] 7
#> 

# Stop the backend.
stop_backend(backend)