Export and document threading helpers

Author: eddelbuettel

DESCRIPTION

@@ -35,3 +35,4 @@ Imports: Rcpp (>= 0.11.0), stats, utils
 Suggests: Matrix, inline, tinytest, pkgKitten, microbenchmark
 URL: https://github.com/RcppCore/RcppEigen, https://dirk.eddelbuettel.com/code/rcpp.eigen.html
 BugReports: https://github.com/RcppCore/RcppEigen/issues
+RoxygenNote: 6.0.1

NAMESPACE

@@ -2,10 +2,14 @@ useDynLib("RcppEigen", .registration=TRUE)
 
 importFrom("Rcpp", "evalCpp")
 importFrom("utils", "packageDescription", "package.skeleton")
-importFrom("stats", "model.frame", "model.matrix", "model.response", "fitted", "coef", "printCoefmat", "pt")
+importFrom("stats", "model.frame", "model.matrix", "model.response", "fitted", "coef", "printCoefmat", "pt", "na.omit")
 export("fastLm",
        "fastLmPure",
-       "RcppEigen.package.skeleton"
+       "RcppEigen.package.skeleton",
+       "EigenNbThreads",
+       "EigenSetNbThreads",
+       "RcppEigen_throttle_cores",
+       "RcppEigen_reset_cores"
        )
 
 S3method("fastLm", "default")

R/RcppExports.R

@@ -13,10 +13,12 @@ Eigen_SSE <- function() {
     .Call(`_RcppEigen_Eigen_SSE`)
 }
 
+#' @rdname RcppEigen_throttle_cores
 EigenNbThreads <- function() {
     .Call(`_RcppEigen_EigenNbThreads`)
 }
 
+#' @rdname RcppEigen_throttle_cores
 EigenSetNbThreads <- function(n) {
     invisible(.Call(`_RcppEigen_EigenSetNbThreads`, n))
 }

R/init.R

@@ -35,12 +35,16 @@
 ##' Helper functions to throttle use of cores by RcppEigen-internal code.
 ##' On package load, the initial value is saved and used to reset the value.
 ##' @param n Integer value of desired cores, default is two
+##' @return Only \code{EigenNbThreads()} returns a value, the current value of
+##' the number of cores used. The other functions are invoked for their side-effect
+##' of affecting the core count.
+##' @seealso \code{\link{RcppEigen-package}}
 RcppEigen_throttle_cores <- function(n) {
     if (missing(n)) n <- .pkgenv[["nb_threads"]]
     EigenSetNbThreads(n)
 }
 
-##'@ rdname RcppEigen_throttle_cores
+##' @rdname RcppEigen_throttle_cores
 RcppEigen_reset_cores <- function() {
     EigenSetNbThreads(.pkgenv[["nb_threads"]])
 }

man/RcppEigen-package.Rd

@@ -16,9 +16,23 @@ Rcpp/Eigen bridge
   other packages.  The C++ source code and the R source code in this
   package are for illustration only.
 
-  As described at the Eigen project's home page,
-  \url{http://eigen.tuxfamily.org/index.php?title=Main_Page}, Eigen is a versatile, fast, reliable
-  and elegant collection of C++ classes for linear algebra.
+  As described at the \href{https://libeigen.gitlab.io/}{Eigen project home
+  page} , Eigen is a a C++ template library for linear algebra: matrices,
+  vectors, numerical solvers, and related algorithms.
+}
+\section{Threading}{
+  The Eigen library can take advantage of OpenMP to execute computations in
+  parallel via multi-threaded code. The number of cores uses can be set (or
+  retrieved) explicitly via helper functions \code{EigenSetNbThreads()} and
+  \code{EigenNbThreads()}. A default value is stored at package startup; it
+  recognises R option value \code{Ncpus} and environment variable
+  \code{OMP_THREAD_LIMITS}.  Additional helper functions
+  \code{RcppEigen_throttle_cores()} and \code{RcppEigen_reset_cores()} are
+  available to (temporarily) lower the number of cores uses and to reset to
+  the package default value set at startup.
+}
+\seealso{
+  \code{\link{RcppEigen_throttle_cores}}
 }
 \references{
   Douglas Bates and Dirk Eddelbuettel (2013). Fast and Elegant Numerical

man/RcppEigen_throttle_cores.Rd

@@ -49,11 +49,13 @@ bool Eigen_SSE() {
     return Rcpp::wrap(Eigen::SimdInstructionSetsInUse());
 }
 
+//' @rdname RcppEigen_throttle_cores
 // [[Rcpp::export]]
 int EigenNbThreads() {
     return Eigen::nbThreads();
 }
 
+//' @rdname RcppEigen_throttle_cores
 // [[Rcpp::export]]
 void EigenSetNbThreads(int n) {
     Eigen::setNbThreads(n);