Title:	'foreach' Parallel Adapter for 'parabar' Backends
Version:	1.0.2
Description:	Provides a 'foreach' parallel adapter for 'parabar' backends. This package offers a minimal implementation of the '%dopar%' operator, enabling users to run 'foreach' loops in parallel, leveraging the parallel and progress-tracking capabilities of the 'parabar' package. Learn more about 'parabar' and 'doParabar' at https://parabar.mihaiconstantin.com.
License:	MIT + file LICENSE
URL:	https://github.com/mihaiconstantin/doParabar, https://parabar.mihaiconstantin.com/articles/foreach
BugReports:	https://github.com/mihaiconstantin/doParabar/issues
Imports:	parabar, foreach, iterators, utils
Encoding:	UTF-8
RoxygenNote:	7.3.1
Collate:	'doPar.R' 'doParabar-package.R' 'helpers.R' 'logo.R' 'registerDoParabar.R'
Suggests:	testthat (≥ 3.0.0)
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2024-12-18 10:34:28 UTC; mihai
Author:	Mihai Constantin [aut, cre]
Maintainer:	Mihai Constantin <mihai@mihaiconstantin.com>
Repository:	CRAN
Date/Publication:	2024-12-19 16:00:05 UTC

Foreach Parallel Adaptor For parabar Backends

Description

Provides a 'foreach' parallel adapter for 'parabar' backends. This package offers a minimal implementation of the '

Details

The doParabar package acts as a foreach::foreach parallel adaptor for parabar::parabar backends. It provides a minimal implementation for the foreach::%dopar% operator, enabling seamless integration of the parabar::parabar package with the foreach::foreach package.

Package Loading

By default, and for various reasons, the doParabar package does not automatically load other packages. Instead, I recommended to load the foreach::foreach and parabar::parabar packages explicitly in your scripts (i.e., or add them to your Imports in the DESCRIPTION file when developing an R package). Package startup messages can be suppressed via base::suppressPackageStartupMessages().

Automatic Exporting

Note that doParabar does not automatically export variables to the backend. Instead, I strongly recommend being explicit about what you want to export to the backend and use the .export and .noexport arguments. Similarly, the .packages argument can be used to indicate which packages should be loaded on the backend. Please check the Details section of the documentation for doPar() for all supported arguments.

Resources

• For more information about parabar::parabar, please consult de documentation and examples at parabar.mihaiconstantin.com.

• For specific information about using parabar::parabar in conjunction with foreach::foreach please check the online vignette at parabar.mihaiconstantin.com/articles/foreach.

Author(s)

Maintainer: Mihai Constantin mihai@mihaiconstantin.com (ORCID)

See Also

Useful links:

• https://github.com/mihaiconstantin/doParabar

• https://parabar.mihaiconstantin.com/articles/foreach

• Report bugs at https://github.com/mihaiconstantin/doParabar/issues

The Package Logo

Description

The logo is generated by parabar::make_logo() and displayed on package attach for interactive R sessions.

Usage

LOGO

Format

An object of class character containing the ASCII logo.

Details

The logo is based on the doParabar-logo.txt template file located under the inst/assets directory of the package.

See Also

parabar::make_logo()

Print Debug Message

Description

This function is used internally to print debug messages when the verbose mode is enabled.

Usage

debugMessage(message, verbose = FALSE)

Arguments

Value

This function returns void.

⁠%dopar%⁠ Implementation For parabar Backends

Description

See the documentation of foreach::foreach-ext for more information on how to provide an implementation for the foreach::%dopar% operator.

Usage

doPar(obj, expr, envir, data)

Details

Currently, the following foreach::foreach arguments are supported:

Value

A list containing the results of the parallel computation.

Get the Number of Workers

Description

Get the Number of Workers

Usage

getNumberOfWorkers(backend)

Arguments

Value

An integer representing the number of workers for the registered backend.

Registered Implementation Information

Description

This function is used internally by foreach::foreach to retrieve information about the registered foreach::%dopar% operator implementation. More specifically, this function is called by foreach::getDoParName(), foreach::getDoParRegistered(), foreach::getDoParVersion(), and foreach::getDoParWorkers().

Usage

parabarInfo(data, item)

Arguments

Value

The requested information item.

Register Parallel Implementation

Description

The registerDoParabar() function registers the provided backend created by parabar::start_backend() to be used as the parallel processing backend for the foreach::%dopar% operator implementation.

Usage

registerDoParabar(backend)

Arguments

Details

Additional information about the registered parallel backend can be extracted using the foreach::getDoParName(), foreach::getDoParRegistered(), foreach::getDoParVersion(), and foreach::getDoParWorkers() functions. See the Examples section.

Value

The registerDoParabar() function returns void.

Completeness

The parallel backend implementation for the foreach::%dopar% operator is provided by the doPar() function. Please check the Details section of its documentation to understand the extent of completeness of the implementation.

See Also

doParabar, doPar(), parabar::start_backend() and parabar::stop_backend().

Examples

# Manually load the libraries.
library(doParabar)
library(parabar)
library(foreach)

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

# Register the backend with the `foreach` package for the `%dopar%` operator.
registerDoParabar(backend)

# Get the parallel backend name.
getDoParName()

# Check that the parallel backend has been registered.
getDoParRegistered()

# Get the current version of backend registration.
getDoParVersion()

# Get the number of cores used by the backend.
getDoParWorkers()

# Define some variables strangers to the backend.
x <- 10
y <- 100
z <- "Not to be exported."

# Used the registered backend to run a task in parallel via `foreach`.
results <- foreach(i = 1:300, .export = c("x", "y"), .combine = c) %dopar% {
    # Sleep a bit.
    Sys.sleep(0.01)

    # Compute and return.
    i + x + y
}

# Show a few results.
head(results, n = 10)
tail(results, n = 10)

# Verify that the variable `z` was not exported.
try(evaluate(backend, z))

# To make packages available on the backend, see the `.packages` argument.

# Stop the backend.
stop_backend(backend)