Skip to content

Commit 4c5a87a

Browse files
kevinusheykevinushey
committed
switch to roxygen
1 parent 98c4206 commit 4c5a87a

15 files changed

+330
-178
lines changed

‎DESCRIPTION‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,3 +33,5 @@ License: GPL (>= 2)
3333
URL: https://rcppcore.github.io/RcppParallel/, https://github.com/RcppCore/RcppParallel
3434
BugReports: https://github.com/RcppCore/RcppParallel/issues
3535
Biarch: TRUE
36+
RoxygenNote: 7.1.1
37+
Encoding: UTF-8

‎NAMESPACE‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
1-
export(setThreadOptions)
2-
export(defaultNumThreads)
3-
export(RcppParallelLibs)
1+
# Generated by roxygen2: do not edit by hand
2+
43
export(CxxFlags)
54
export(LdFlags)
65
export(RcppParallel.package.skeleton)
6+
export(RcppParallelLibs)
7+
export(defaultNumThreads)
8+
export(setThreadOptions)

‎R/RcppParallel-package.R‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
2+
3+
#' Parallel programming tools for Rcpp
4+
#'
5+
#' High level functions for doing parallel programming with Rcpp. For example,
6+
#' the `parallelFor()` function can be used to convert the work of a
7+
#' standard serial "for" loop into a parallel one, and the `parallelReduce()`
8+
#' function can be used for accumulating aggregate or other values.
9+
#'
10+
#' The high level interface enables safe and robust parallel programming
11+
#' without direct manipulation of operating system threads. On Windows, macOS,
12+
#' and Linux systems the underlying implementation is based on Intel TBB
13+
#' (Threading Building Blocks). On other platforms a less-performant fallback
14+
#' implementation based on the TinyThread library is used.
15+
#'
16+
#' For additional documentation, see the package website at:
17+
#'
18+
#' <https://rcppcore.github.io/RcppParallel>
19+
#'
20+
#'
21+
#' @name RcppParallel-package
22+
#' @docType package
23+
#' @aliases RcppParallel RcppParallel-package
24+
#' @keywords package parallel
25+
NULL

R/build.R renamed to R/flags.R

Lines changed: 40 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,57 @@
11

2+
#' Compilation flags for RcppParallel
3+
#'
4+
#' Output the compiler or linker flags required to build against RcppParallel.
5+
#'
6+
#' These functions are typically called from \code{Makevars} as follows:
7+
#'
8+
#' ```
9+
#' PKG_LIBS += $(shell "${R_HOME}/bin/Rscript" -e "RcppParallel::LdFlags()")
10+
#' ```
11+
#'
12+
#' On Windows, the flags ensure that the package links with the built-in TBB
13+
#' library. On Linux and macOS, the output is empty, because TBB is loaded
14+
#' dynamically.
15+
#'
16+
#' To ensure portability, load \pkg{RcppParallel} before loading
17+
#' your package, e.g. by including \code{importFrom(RcppParallel,
18+
#' RcppParallelLibs)} in your \code{NAMESPACE} file. See
19+
#' \url{https://github.com/RcppCore/RcppParallel/issues/129} for details.
20+
#'
21+
#' @name flags
22+
#' @rdname flags
23+
#' @aliases RcppParallelLibs LdFlags CxxFlags
24+
#'
25+
#' @return Returns \code{NULL}, invisibly. These functions are called for
26+
#' their side effects (writing the associated flags to stdout).
27+
#'
28+
NULL
229

3-
# Output the CXX flags. These flags are propagated to sourceCpp via the
4-
# inlineCxxPlugin (defined below) and to packages via a line in Makevars[.win]
5-
# like this:
6-
#
7-
# PKG_CXXFLAGS += $(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript.exe" -e "RcppParallel::CxxFlags()")
8-
#
30+
31+
#' @name flags
32+
#' @export
933
CxxFlags <- function() {
1034
cat(tbbCxxFlags())
1135
}
1236

13-
14-
# Output the LD flags for building against TBB. These flags are propagated
15-
# to sourceCpp via the inlineCxxPlugin (defined below) and to packages
16-
# via a line in Makevars[.win] like this:
17-
#
18-
# PKG_LIBS += $(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript.exe" -e "RcppParallel::LdFlags()")
19-
#
37+
#' @name flags
38+
#' @export
2039
LdFlags <- function() {
2140
cat(tbbLdFlags())
2241
}
2342

24-
# alias for backward compatibility
43+
#' @name flags
44+
#' @export
2545
RcppParallelLibs <- function() {
2646
LdFlags()
2747
}
2848

29-
# Inline plugin used by sourceCpp.
30-
inlineCxxPlugin <- function() {
31-
32-
env <- list(
33-
PKG_CXXFLAGS = tbbCxxFlags(),
34-
PKG_LIBS = tbbLdFlags()
35-
)
36-
37-
list(
38-
env = env,
39-
body = identity,
40-
includes = "#include <RcppParallel.h>",
41-
LinkingTo = "RcppParallel",
42-
Depends = "RcppParallel"
43-
)
44-
45-
}
4649

47-
tbbCxxFlags <- function() {
4850

51+
tbbCxxFlags <- function() {
52+
4953
flags <- character()
50-
54+
5155
# opt-in to TBB on Windows
5256
if (is_windows())
5357
flags <- c(flags, "-DRCPP_PARALLEL_USE_TBB=1")
@@ -65,7 +69,7 @@ tbbCxxFlags <- function() {
6569
flags <- c(flags, "-DTBB_INTERFACE_NEW")
6670

6771
}
68-
72+
6973
# return flags as string
7074
paste(flags, collapse = " ")
7175

@@ -129,7 +133,7 @@ tbbLibPath <- function(suffix = "") {
129133
if (file.exists(tbbName))
130134
return(tbbName)
131135
}
132-
136+
133137
}
134138

135139
# Helper function to ape the behavior of the R build system
@@ -149,4 +153,5 @@ asBuildPath <- function(path) {
149153

150154
# return path
151155
return(path)
156+
152157
}

‎R/hooks.R‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,24 @@ mallocDllInfo <- NULL
2323
}
2424
}
2525

26-
# load the package library
27-
library.dynam("RcppParallel", pkgname, libname)
26+
# work around roxygen2 issue
27+
documenting <- FALSE
28+
checks <- list(
29+
call("::", as.symbol("devtools"), as.symbol("document")),
30+
call("::", as.symbol("roxygen2"), as.symbol("roxygenize"))
31+
)
32+
33+
for (call in sys.calls()) {
34+
for (check in checks) {
35+
if (identical(call[[1L]], check)) {
36+
documenting <- TRUE
37+
break
38+
}
39+
}
40+
}
41+
42+
if (!documenting)
43+
library.dynam("RcppParallel", pkgname, libname)
2844

2945
}
3046

‎R/options.R‎

Lines changed: 52 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,48 @@
11

2-
isUsingTbb <- function() {
3-
backend <- Sys.getenv("RCPP_PARALLEL_BACKEND", "tbb")
4-
identical(backend, "tbb")
5-
}
6-
7-
setThreadOptions <- function(numThreads = "auto", stackSize = "auto") {
8-
2+
#' Thread options for RcppParallel
3+
#'
4+
#' Set thread options (number of threads to use for task scheduling and stack
5+
#' size per-thread) for RcppParallel.
6+
#'
7+
#' RcppParallel is automatically initialized with the default number of threads
8+
#' and thread stack size when it loads. You can call `setThreadOptions()` at
9+
#' any time to change the defaults.
10+
#'
11+
#' The `parallelFor()` and `parallelReduce()` also accept `numThreads` as
12+
#' an argument, if you'd like to control the number of threads specifically
13+
#' to be made available for a particular parallel function call. Note that
14+
#' this value is advisory, and TBB may choose a smaller number of threads
15+
#' if the number of requested threads cannot be honored on the system.
16+
#'
17+
#' @aliases setThreadOptions defaultNumThreads
18+
#'
19+
#' @param numThreads
20+
#' Number of threads to use for task scheduling. Call `defaultNumThreads()`
21+
#' to determine the the default value used for "auto".
22+
#'
23+
#' @param stackSize
24+
#' Stack size (in bytes) to use for worker threads. The
25+
#' default used for "auto" is 2MB on 32-bit systems and 4MB on 64-bit systems
26+
#' (note that this parameter has no effect on Windows).
27+
#'
28+
#' @return
29+
#' `defaultNumThreads()` returns the default number of threads used by
30+
#' RcppParallel, if another value isn't specified either via
31+
#' `setThreadOptions()` or explicitly in calls to `parallelFor()` and
32+
#' `parallelReduce()`.
33+
#'
34+
#' @examples
35+
#'
36+
#' \dontrun{
37+
#' library(RcppParallel)
38+
#' setThreadOptions(numThreads = 4)
39+
#' defaultNumThreads()
40+
#' }
41+
#'
42+
#' @export setThreadOptions
43+
setThreadOptions <- function(numThreads = "auto",
44+
stackSize = "auto")
45+
{
946
# validate and resolve numThreads
1047
if (identical(numThreads, "auto"))
1148
numThreads <- -1L
@@ -33,9 +70,16 @@ setThreadOptions <- function(numThreads = "auto", stackSize = "auto") {
3370
Sys.unsetenv("RCPP_PARALLEL_STACK_SIZE")
3471
else
3572
Sys.setenv(RCPP_PARALLEL_STACK_SIZE = stackSize)
36-
3773
}
3874

75+
#' @rdname setThreadOptions
76+
#' @export
3977
defaultNumThreads <- function() {
4078
.Call("defaultNumThreads", PACKAGE = "RcppParallel")
4179
}
80+
81+
isUsingTbb <- function() {
82+
backend <- Sys.getenv("RCPP_PARALLEL_BACKEND", "tbb")
83+
identical(backend, "tbb")
84+
}
85+

‎R/skeleton.R‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,53 @@
1+
2+
#' Create a skeleton for a new package depending on RcppParallel
3+
#'
4+
#' \code{RcppParallel.package.skeleton} automates the creation of a new source
5+
#' package that intends to use features of RcppParallel.
6+
#'
7+
#' It is based on the \link[utils]{package.skeleton} function which it executes
8+
#' first.
9+
#'
10+
#' In addition to \link[Rcpp]{Rcpp.package.skeleton} :
11+
#'
12+
#' The \samp{DESCRIPTION} file gains an Imports line requesting that the
13+
#' package depends on RcppParallel and a LinkingTo line so that the package
14+
#' finds RcppParallel header files.
15+
#'
16+
#' The \samp{NAMESPACE} gains a \code{useDynLib} directive as well as an
17+
#' \code{importFrom(RcppParallel, evalCpp} to ensure instantiation of
18+
#' RcppParallel.
19+
#'
20+
#' The \samp{src} directory is created if it does not exists and a
21+
#' \samp{Makevars} file is added setting the environment variables
22+
#' \samp{PKG_LIBS} to accomodate the necessary flags to link with the
23+
#' RcppParallel library.
24+
#'
25+
#' If the \code{example_code} argument is set to \code{TRUE}, example files
26+
#' \samp{vector-sum.cpp} is created in the \samp{src} directory.
27+
#' \code{Rcpp::compileAttributes()} is then called to generate
28+
#' \code{src/RcppExports.cpp} and \code{R/RcppExports.R}. These files are given
29+
#' as an example and should eventually by removed from the generated package.
30+
#'
31+
#' @param name The name of your R package.
32+
#' @param example_code If \code{TRUE}, example C++ code using RcppParallel is
33+
#' added to the package.
34+
#' @param ... Optional arguments passed to \link[Rcpp]{Rcpp.package.skeleton}.
35+
#' @return Nothing, used for its side effects
36+
#' @seealso \link[utils]{package.skeleton}
37+
#' @references Read the \emph{Writing R Extensions} manual for more details.
38+
#'
39+
#' Once you have created a \emph{source} package you need to install it: see
40+
#' the \emph{R Installation and Administration} manual, \code{\link{INSTALL}}
41+
#' and \code{\link{install.packages}}.
42+
#' @keywords programming
43+
#' @examples
44+
#'
45+
#' \dontrun{
46+
#' # simple package
47+
#' RcppParallel.package.skeleton("foobar")
48+
#' }
49+
#'
50+
#' @export RcppParallel.package.skeleton
151
RcppParallel.package.skeleton <- function(name = "anRpackage",
252
example_code = TRUE,
353
...)

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88

99
High level functions for parallel programming with Rcpp. 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.
1010

11-
The high level interface enables safe and robust parallel programming without direct manipulation of operating system threads. On Windows, OS X, and Linux systems, the underlying implementation is based on [Intel TBB](https://www.threadingbuildingblocks.org/) (Threading Building Blocks). On other platforms, a less-performant fallback implementation based on the [TinyThread](http://tinythreadpp.bitsnbites.eu/) library is used.
11+
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](https://www.threadingbuildingblocks.org/) (Threading Building Blocks). On other platforms, a less-performant fallback implementation based on the [TinyThread](http://tinythreadpp.bitsnbites.eu/) library is used.
1212

1313
For additional documentation on using RcppParallel see the package website at http://rcppcore.github.io/RcppParallel/.
1414

‎RcppParallel.Rproj‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,4 @@ LaTeX: pdfLaTeX
1515
BuildType: Package
1616
PackageInstallArgs: --with-keep.source --clean
1717
PackageCheckArgs: --as-cran
18+
PackageRoxygenize: rd,collate,namespace,vignette

‎inst/include/tthread/tinythread.h‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -130,8 +130,8 @@ freely, subject to the following restrictions:
130130
/// destructors) to be declared with the @c thread_local keyword, most pre-C++11
131131
/// compilers only allow for trivial types (e.g. @c int). So, to guarantee
132132
/// portable code, only use trivial types for thread local storage.
133-
/// @note This directive is currently not supported on Mac OS X (it will give
134-
/// a compiler error), since compile-time TLS is not supported in the Mac OS X
133+
/// @note This directive is currently not supported on Mac macOS (it will give
134+
/// a compiler error), since compile-time TLS is not supported in the Mac macOS
135135
/// executable format. Also, some older versions of MinGW (before GCC 4.x) do
136136
/// not support this directive.
137137
/// @hideinitializer

0 commit comments

Comments
 (0)