Title: | Parallel Programming Tools for 'Rcpp' |
---|---|
Description: | High level functions for parallel programming with 'Rcpp'. For example, the 'parallelFor()' function can be used to convert the work of a standard serial "for" loop into a parallel one and the 'parallelReduce()' function can be used for accumulating aggregate or other values. |
Authors: | JJ Allaire [aut], Romain Francois [aut, cph], Kevin Ushey [aut, cre], Gregory Vandenbrouck [aut], Marcus Geelnard [aut, cph] (TinyThread library, https://tinythreadpp.bitsnbites.eu/), Hamada S. Badr [ctb] , Posit, PBC [cph], Intel [aut, cph] (Intel TBB library, https://www.threadingbuildingblocks.org/), Microsoft [cph] |
Maintainer: | Kevin Ushey <[email protected]> |
License: | GPL (>= 3) |
Version: | 5.1.9.9000 |
Built: | 2024-09-27 19:27:24 UTC |
Source: | https://github.com/rcppcore/rcppparallel |
High level functions for doing parallel programming with Rcpp. For example,
the parallelFor()
function can be used to convert the work of a
standard serial "for" loop into a parallel one, and the parallelReduce()
function can be used for accumulating aggregate or other values.
The high level interface enables safe and robust parallel programming without direct manipulation of operating system threads. On Windows, macOS, and Linux systems the underlying implementation is based on Intel TBB (Threading Building Blocks). On other platforms, a less-performant fallback implementation based on the TinyThread library is used.
For additional documentation, see the package website at:
https://rcppcore.github.io/RcppParallel/
Output the compiler or linker flags required to build against RcppParallel.
CxxFlags() LdFlags() RcppParallelLibs()
CxxFlags() LdFlags() RcppParallelLibs()
These functions are typically called from Makevars
as follows:
PKG_LIBS += $(shell "${R_HOME}/bin/Rscript" -e "RcppParallel::LdFlags()")
On Windows, the flags ensure that the package links with the built-in TBB
library. On Linux and macOS, the output is empty, because TBB is loaded
dynamically on load by RcppParallel
.
R packages using RcppParallel should also add the following to their
NAMESPACE
file:
importFrom(RcppParallel, RcppParallelLibs)
This is necessary to ensure that RcppParallel (and so, TBB) is loaded and available.
Returns NULL
, invisibly. These functions are called for
their side effects (writing the associated flags to stdout).
RcppParallel.package.skeleton
automates the creation of a new source
package that intends to use features of RcppParallel.
RcppParallel.package.skeleton(name = "anRpackage", example_code = TRUE, ...)
RcppParallel.package.skeleton(name = "anRpackage", example_code = TRUE, ...)
name |
The name of your R package. |
example_code |
If |
... |
Optional arguments passed to Rcpp.package.skeleton. |
It is based on the package.skeleton function which it executes first.
In addition to Rcpp.package.skeleton :
The ‘DESCRIPTION’ file gains an Imports line requesting that the package depends on RcppParallel and a LinkingTo line so that the package finds RcppParallel header files.
The ‘NAMESPACE’ gains a useDynLib
directive as well as an
importFrom(RcppParallel, evalCpp
to ensure instantiation of
RcppParallel.
The ‘src’ directory is created if it does not exists and a ‘Makevars’ file is added setting the environment variables ‘PKG_LIBS’ to accomodate the necessary flags to link with the RcppParallel library.
If the example_code
argument is set to TRUE
, example files
‘vector-sum.cpp’ is created in the ‘src’ directory.
Rcpp::compileAttributes()
is then called to generate
src/RcppExports.cpp
and R/RcppExports.R
. These files are given
as an example and should eventually by removed from the generated package.
Nothing, used for its side effects
Read the Writing R Extensions manual for more details.
Once you have created a source package you need to install it: see
the R Installation and Administration manual, INSTALL
and install.packages
.
## Not run: # simple package RcppParallel.package.skeleton("foobar") ## End(Not run)
## Not run: # simple package RcppParallel.package.skeleton("foobar") ## End(Not run)
Set thread options (number of threads to use for task scheduling and stack size per-thread) for RcppParallel.
setThreadOptions(numThreads = "auto", stackSize = "auto") defaultNumThreads()
setThreadOptions(numThreads = "auto", stackSize = "auto") defaultNumThreads()
numThreads |
Number of threads to use for task scheduling. Call |
stackSize |
Stack size (in bytes) to use for worker threads. The default used for "auto" is 2MB on 32-bit systems and 4MB on 64-bit systems (note that this parameter has no effect on Windows). |
RcppParallel is automatically initialized with the default number of threads
and thread stack size when it loads. You can call setThreadOptions()
at
any time to change the defaults.
The parallelFor()
and parallelReduce()
also accept numThreads
as
an argument, if you'd like to control the number of threads specifically
to be made available for a particular parallel function call. Note that
this value is advisory, and TBB may choose a smaller number of threads
if the number of requested threads cannot be honored on the system.
defaultNumThreads()
returns the default number of threads used by
RcppParallel, if another value isn't specified either via
setThreadOptions()
or explicitly in calls to parallelFor()
and
parallelReduce()
.
## Not run: library(RcppParallel) setThreadOptions(numThreads = 4) defaultNumThreads() ## End(Not run)
## Not run: library(RcppParallel) setThreadOptions(numThreads = 4) defaultNumThreads() ## End(Not run)
Retrieve the path to a TBB library. This can be useful for R packages using RcppParallel that wish to use, or re-use, the version of TBB that RcppParallel has been configured to use.
tbbLibraryPath(name = NULL)
tbbLibraryPath(name = NULL)
name |
The name of the TBB library to be resolved. Normally, this is one of
|