% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/doFuture-package.R
\docType{package}
\name{doFuture}
\alias{doFuture}
\alias{doFuture-package}
\title{doFuture: Foreach Parallel Adapter using Futures}
\description{
The \pkg{doFuture} package provides mechanisms for using the
\pkg{foreach} package together with the \pkg{future} package
such that \code{foreach()} parallelizes via \emph{any} future backend.
There are three alternative ways to use this package:
\enumerate{
\item \code{y <- foreach(...) \%do\% { ... } |> futurize()}
\item \code{y <- foreach(...) \%dofuture\% { ... }}
\item \code{y <- foreach(...) \%dopar\% { ... }} with \code{registerDoFuture()}
}
}
\section{foreach() with \%do\% and futurize() (recommended)}{

The \emph{first alternative} (recommended) uses \code{futurize()} of the
\href{https://cran.r-project.org/package=futurize}{\pkg{futurize}} package.
An example is:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{library(futurize)
plan(multisession)

y <- foreach(x = 1:4, y = 1:10) \%do\% \{
  z <- x + y
  slow_sqrt(z)
\} |> futurize()
}\if{html}{\out{</div>}}

This alternative is the recommended and most clean way to let \code{foreach()}
parallelize via the future framework if you start out from scratch.
All you need to remember is to pipe it to \code{futurize()}, and, yes, it is
correct to use \verb{\%do\%} here.
In addition to \code{multisession}, parallelization can be done via any of
the compliant \href{https://www.futureverse.org/backends.html}{future backends}.
Identification of globals, random number generation (RNG), and error
handling is handled the same way as elsewhere in the future ecosystem.
We recommend to use \code{futurize()}, because it is consistent with how we
parallelize \code{lapply()} and \code{purrr::map()} using \strong{futurize}.
With \code{futurize()}, you do not have to explicitly load \strong{doFuture} -
instead \strong{doFuture} will serve \code{futurize()} under the hood.
}

\section{foreach() with \%dofuture\%}{

The \emph{second alternative} (formerly recommended), which uses
\code{\link{\%dofuture\%}}, is what \code{futurize()} does automatically under the hood,
and they are effectively the same.
An example is:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{library(doFuture)
plan(multisession)

y <- foreach(x = 1:4, y = 1:10) \%dofuture\% \{
  z <- x + y
  slow_sqrt(z)
\}
}\if{html}{\out{</div>}}

This alternative is the formerly recommended way to let \code{foreach()}
parallelize via the future framework if you start out from scratch,
but we now recommend \code{futurize()} because it keeps the code neater.
See \code{\link{\%dofuture\%}} for more details and examples on this approach.
}

\section{foreach() with \%dopar\% and registerDoFuture()}{

The \emph{third alternative} is based on the traditional \strong{foreach}
approach where one registers a foreach adapter to be used by \verb{\%dopar\%}.
Contrary to above two approaches, you must not forget to register a
foreach adapter in order parallelize. This package provides
\code{registerDoFuture()}, which causes `\%dopar\% to parallelize via the
future framework.
An example is:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{library(doFuture)
registerDoFuture()
plan(multisession)

y <- foreach(x = 1:4, y = 1:10) \%dopar\% \{
  z <- x + y
  slow_sqrt(z)
\}
}\if{html}{\out{</div>}}

This alternative is useful if you already have a lot of R code that
uses \verb{\%dopar\%} and you just want to switch to using the future
framework for parallelization.  Using \code{registerDoFuture()} is also
useful when you wish to use the future framework with packages and
functions that use \code{foreach()} and \verb{\%dopar\%} internally, but does not
yet support the \code{futurize()} approach, e.g. \strong{\href{https://cran.r-project.org/package=NMF}{NMF}}.
See \code{\link[=registerDoFuture]{registerDoFuture()}} for more details and examples on this approach.
}

\seealso{
Useful links:
\itemize{
  \item \url{https://doFuture.futureverse.org}
  \item \url{https://github.com/futureverse/doFuture}
  \item Report bugs at \url{https://github.com/futureverse/doFuture/issues}
}

}
\author{
\strong{Maintainer}: Henrik Bengtsson \email{henrikb@braju.com} (\href{https://orcid.org/0000-0002-7579-5165}{ORCID}) [copyright holder]

Authors:
\itemize{
  \item Henrik Bengtsson \email{henrikb@braju.com} (\href{https://orcid.org/0000-0002-7579-5165}{ORCID}) [copyright holder]
}

}
