add tbbLibPath; update NEWS

Author: kevinushey

NAMESPACE

@@ -6,3 +6,4 @@ export(RcppParallel.package.skeleton)
 export(RcppParallelLibs)
 export(defaultNumThreads)
 export(setThreadOptions)
+export(tbbLibPath)

inst/NEWS renamed to NEWS.md

@@ -1,114 +1,135 @@
-RcppParallel 5.1.1
-------------------------------------------------------------------------
+## RcppParallel 5.1.2 (UNRELEASED)
 
-* Updated bundled version of TBB (Intel TBB 2019 Update 8)
-* Added support for external TBB library using TBB_INC and TBB_LIB environment variables.
+* `RcppParallel` gains the `tbbLibPath()` function, to be used when attempting
+  to query the location of the TBB libraries that `RcppParallel` has been
+  configured to use. This may be useful for R packages which wish to explicitly
+  use, or link to, these libraries.
+
+## RcppParallel 5.1.1
+
+* Updated bundled version of TBB (Intel TBB 2019 Update 8).
+
+* RcppParallel can now be configured to use an external copy of TBB, via the
+  `TBB_LIB` and `TBB_INC` environment variables. These should be set to the
+  directories containing the TBB libraries and headers, respectively.
+  
 * Added support for the latest versions of Intel oneAPI TBB / oneTBB.
+
 * Updated TBB functionality for the new interface.
+
 * Falling back to building TBB from local source code.
+
 * Backward TBB compatibility based on `__TBB_tbb_stddef_H`.
+
 * Resolved conflicts between system and local TBB headers.
+
 * Fixed URLs, used HTTPS, and minor cleanups.
+
 * Updated package DESCRIPTION and bumped version.
-* setThreadOptions(...) can again be called multiple times per session.
-  The requested number of threads will be used for invocations to parallelFor()
-  and parallelReduce() that don't explicitly request a specific number of threads.
-* The parallelFor() and parallelReduce() functions gain the 'numThreads'
+
+* `setThreadOptions(...)` can again be called multiple times per session.
+  The requested number of threads will be used for invocations to `parallelFor()`
+  and `parallelReduce()` that don't explicitly request a specific number of threads.
+  
+* The `parallelFor()` and `parallelReduce()` functions gain the `numThreads`
   argument, allowing one to limit the number of threads used for a
   particular computation.
 
-RcppParallel 5.0.3
-------------------------------------------------------------------------
+## RcppParallel 5.0.3
+
 * Fixed compilation on macOS M1 machines.
 
-RcppParallel 5.0.2
-------------------------------------------------------------------------
+## RcppParallel 5.0.2
 
-* setThreadOptions(...) can now only be called once per session, to avoid
+* `setThreadOptions(...)` can now only be called once per session, to avoid
   segfaults when compiling RcppParallel / TBB with gcc 10.1. Subsequent
-  calls to setThreadOptions(...) are ignored.
+  calls to `setThreadOptions(...)` are ignored.
 
-RcppParallel 5.0.1
-------------------------------------------------------------------------
+## RcppParallel 5.0.1
 
 * Fixed compilation issue on OpenSUSE Tumbleweed with -flto=auto
+
 * Fixed compilation when CPPFLAGS = -I/usr/local/include and a version
   of libtbb is installed there
 
-RcppParallel 5.0.0
-------------------------------------------------------------------------
+## RcppParallel 5.0.0
 
 * RcppParallel backend can now be customized with RCPP_PARALLEL_BACKEND
   environment variable (supported values are 'tbb' and 'tinythread')
+  
 * Fixed issue when compiling RcppParallel on macOS Catalina
+
 * Fixed issue when compiling RcppParallel with Rtools40
 
-RcppParallel 4.4.4
-------------------------------------------------------------------------
+## RcppParallel 4.4.4
 
 * Fixed an issue when compiling RcppParallel with clang-9 on Fedora
 
-RcppParallel 4.4.3
-------------------------------------------------------------------------
+## RcppParallel 4.4.3
 
 * Suppress gcc-9 warnings related -Wclass-memaccess
+
 * Added TBB headers for serial TBB operations (#90, @mikejiang)
+
 * Fixed row iterator constructor (#87, @wtianyi)
+
 * Fixed compilation on FreeBSD
 
-RcppParallel 4.4.2
-------------------------------------------------------------------------
+## RcppParallel 4.4.2
 
 * Suppress gcc-8 warnings related to -Wclass-memaccess
+
 * Use PKG_CXXFLAGS rather than PKG_CPPFLAGS
+
 * Remove unused dependency on the BH package
 
-RcppParallel 4.4.1
-------------------------------------------------------------------------
+## RcppParallel 4.4.1
 
 * Ensure user-specified R configuration passed to TBB
+
 * Work around warnings emitted by gcc 8
 
-RcppParallel 4.4.0
-------------------------------------------------------------------------
+## RcppParallel 4.4.0
 
 * Respect user-defined compiler settings (e.g. from ~/.R/Makevars).
+
 * Remove TBB's attempts to suppress compiler diagnostics.
+
 * Allow setting the number of threads to use via RCPP_PARALLEL_NUM_THREADS
   environment variable.
+
 * Update to TBB 2018 Update 1.
+
 * Add native registration of compiled functions.
 
-RcppParallel 4.3.20
-------------------------------------------------------------------------
+## RcppParallel 4.3.20
 
 * Add support for Rtools 3.3 w/ GCC 4.9
 
-RcppParallel 4.3.14
-------------------------------------------------------------------------
+## RcppParallel 4.3.14
 
 * Add support for TBB on Solaris
+
 * Fix failure to compile on OS X Snow Leopard R toolchain
+
 * Add const and non-const operator[] for RMatrix class
 
-RcppParallel 4.3.8
-------------------------------------------------------------------------
+## RcppParallel 4.3.8
 
 * Add tbbmalloc library
+
 * Correctly pass clang to TBB configure when R is using clang
 
-RcppParallel 4.3.6
-------------------------------------------------------------------------
+## RcppParallel 4.3.6
 
 * Support for TBB on Windows
 
-RcppParallel 4.3.3
-------------------------------------------------------------------------
+## RcppParallel 4.3.3
 
 * Update to TBB 4.3 (fixes clang compilation error in platform.h)
+
 * Forward CXX to TBB Makefile
 
-RcppParallel 4.2.5
-------------------------------------------------------------------------
+## RcppParallel 4.2.5
 
 * Initial release

R/RcppParallel-package.R

@@ -1,5 +1,4 @@
 
-
 #' Parallel programming tools for Rcpp
 #' 
 #' High level functions for doing parallel programming with Rcpp.  For example,
@@ -10,7 +9,7 @@
 #' 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
+#' (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:

R/flags.R

@@ -3,20 +3,25 @@
 #' 
 #' Output the compiler or linker flags required to build against RcppParallel.
 #' 
-#' These functions are typically called from \code{Makevars} as follows:
+#' 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.
+#' dynamically on load by `RcppParallel`.
 #' 
-#' To ensure portability, load \pkg{RcppParallel} before loading
-#' your package, e.g. by including \code{importFrom(RcppParallel,
-#' RcppParallelLibs)} in your \code{NAMESPACE} file. See
-#' \url{https://github.com/RcppCore/RcppParallel/issues/129} for details.
+#' \R packages using RcppParallel should also add the following to their
+#' `NAMESPACE` file:
+#' 
+#' ```
+#' importFrom(RcppParallel, RcppParallelLibs)
+#' ```
+#' 
+#' This is necessary to ensure that \pkg{RcppParallel} (and so, TBB) is loaded
+#' and available.
 #' 
 #' @name flags
 #' @rdname flags
@@ -46,113 +51,3 @@ RcppParallelLibs <- function() {
    LdFlags()
 }
 
-
-
-tbbCxxFlags <- function() {
-   
-   flags <- character()
-   
-   # opt-in to TBB on Windows
-   if (is_windows())
-      flags <- c(flags, "-DRCPP_PARALLEL_USE_TBB=1")
-   
-   # if TBB_INC is set, apply those library paths
-   tbbInc <- Sys.getenv("TBB_INC", unset = NA)
-   if (!is.na(tbbInc)) {
-      
-      # add include path
-      flags <- c(flags, paste0("-I", shQuote(asBuildPath(tbbInc))))
-      
-      # prefer new interface if version.h exists
-      versionPath <- file.path(tbbInc, "tbb/version.h")
-      if (file.exists(versionPath))
-         flags <- c(flags, "-DTBB_INTERFACE_NEW")
-      
-   }
-   
-   # return flags as string
-   paste(flags, collapse = " ")
-   
-}
-
-# Return the linker flags required for TBB on this platform
-tbbLdFlags <- function() {
-   
-   # shortcut if TBB_LIB defined
-   tbbLib <- Sys.getenv("TBB_LIB", unset = NA)
-   if (!is.na(tbbLib)) {
-      fmt <- "-L%1$s -Wl,-rpath,%1$s -ltbb -ltbbmalloc"
-      return(sprintf(fmt, shQuote(asBuildPath(tbbLib))))
-   }
-   
-   # on Windows and Solaris, we need to explicitly link
-   needsExplicitFlags <- is_windows() || (is_solaris() && !is_sparc())
-   if (needsExplicitFlags) {
-      libPath <- asBuildPath(dirname(tbbLibPath()))
-      libFlag <- paste0("-L", shQuote(libPath))
-      return(paste(libFlag, "-ltbb", "-ltbbmalloc"))
-   }
-   
-   # nothing required on other platforms
-   ""
-   
-}
-
-tbbRoot <- function() {
-   rArch <- .Platform$r_arch
-   parts <- c("libs", if (nzchar(rArch)) rArch, "tbb")
-   libDir <- paste(parts, collapse = "/")
-   system.file(libDir, package = "RcppParallel")
-}
-
-# Determine the platform-specific path to the TBB library
-tbbLibPath <- function(suffix = "") {
-   
-   # library paths for different OSes
-   sysname <- Sys.info()[["sysname"]]
-   
-   tbbLibNames <- list(
-      "Darwin"  = paste0("libtbb", suffix, ".dylib"),
-      "Windows" = paste0("tbb",    suffix, ".dll"),
-      "SunOS"   = paste0("libtbb", suffix, ".so"),
-      "Linux"   = paste0("libtbb", suffix, c(".so.2", ".so"))
-   )
-   
-   # skip systems that we know not to be compatible
-   isCompatible <-
-      !is_sparc() &&
-      !is.null(tbbLibNames[[sysname]])
-   
-   if (!isCompatible)
-      return(NULL)
-   
-   # find root for TBB install
-   tbbRoot <- Sys.getenv("TBB_LIB", unset = tbbRoot())
-   libNames <- tbbLibNames[[sysname]]
-   for (libName in libNames) {
-      tbbName <- file.path(tbbRoot, libName)
-      if (file.exists(tbbName))
-         return(tbbName)
-   }
-   
-}
-
-# Helper function to ape the behavior of the R build system
-# when providing paths to libraries
-asBuildPath <- function(path) {
-   
-   # nothing to do for non-Windows
-   if (!is_windows())
-      return(path)
-   
-   # normalize paths using forward slashes
-   path <- normalizePath(path, winslash = "/", mustWork = FALSE)
-   
-   # prefer short path names if the path has spaces
-   if (grepl(" ", path, fixed = TRUE))
-      path <- utils::shortPathName(path)
-   
-   # return path
-   return(path)
-   
-}

R/hooks.R

@@ -14,7 +14,7 @@ mallocDllInfo <- NULL
       }
    }
 
-   tbbMalloc <- tbbLibPath("malloc")
+   tbbMalloc <- tbbLibPath("tbbmalloc")
    if (!is.null(tbbMalloc)) {
       if (!file.exists(tbbMalloc)) {
          warning(paste("TBB malloc library", tbbMalloc, "not found."))