Refine openmp thread count setting at startup

Author: eddelbuettel

ChangeLog

@@ -1,3 +1,9 @@
+2026-01-03  Dirk Eddelbuettel  <edd@debian.org>
+
+	* R/init.R: Expand openmp core count logic respecting Ncpus and
+	OMP_THREAD_LIMIT else setting all cores; add startup message
+	* man/RcppArmadillo-package.Rd: Document thread count setting options
+
 2025-12-16  Dirk Eddelbuettel  <edd@debian.org>
 
 	* DESCRIPTION (Version, Date): RcppArmadillo 15.2.3-1

R/init.R

@@ -1,6 +1,6 @@
 ## init.R: Startup
 ##
-## Copyright (C)  2023  Dirk Eddelbuettel
+## Copyright (C)  2023-2026  Dirk Eddelbuettel
 ##
 ## This file is part of RcppArmadillo.
 ##
@@ -19,8 +19,23 @@
 
 .pkgenv <- new.env(parent=emptyenv())
 
-.onLoad <- function(libname, pkgname) {
-    .pkgenv[["omp_threads"]] <- armadillo_get_number_of_omp_threads()		# #nocov
+.onLoad <- function(libname, pkgname) {					# nocov start
+    ## simple fallback: 'Ncpus' (if set) or else all cpus seen by OpenMP
+    ncores <- getOption("Ncpus", armadillo_get_number_of_omp_threads())
+    ## consider OMP_THREAD_LIMIT (cf Writing R Extensions), gets NA if envvar unset
+    ompcores <- as.integer(Sys.getenv("OMP_THREAD_LIMIT"))
+    ## keep the smaller value, omitting NA
+    ncores <- min(na.omit(c(ncores, ompcores)))
+    .pkgenv[["nb_threads"]] <- ncores
+    armadillo_throttle_cores(ncores)
+}
+
+.onAttach <- function(libname, pkgname) {
+    if (interactive()) {
+        packageStartupMessage("RcppArmadillo ", packageVersion("RcppArmadillo"),
+                              " using ", .pkgenv[["nb_threads"]], " cores. See ",
+                              "'help(\"RcppArmadillo-package\")' for details.")
+    }
 }
 
 ##' Throttle (or Reset) (Rcpp)Armadillo to Two Cores

man/RcppArmadillo-package.Rd

@@ -3,12 +3,8 @@
 \alias{RcppArmadillo}
 \alias{RcppArmadilloExample}
 \docType{package}
-\title{
-  R and Armadillo Integration
-}
-\description{
-  The package brings the power of Armadillo to R.
-}
+\title{R and Armadillo Integration}
+\description{The package brings the power of Armadillo to R.}
 \section{Armadillo}{
   \code{Armadillo} is a C++ linear algebra library, aiming towards a good
   balance between speed and ease of use.
@@ -28,45 +24,28 @@
   Armadillo has been primarily developed at NICTA (Australia) by Conrad
   Sanderson, with contributions from around the world.
 }
-
 \section{RcppArmadillo}{
   \code{RcppArmadillo} acts as a bridge between \code{Rcpp} and \code{Armadillo},
   allowing the programmer to write code using Armadillo classes that integrate
   seemlessly with \code{R} via \code{Rcpp}.
 }
-
 \section{Using RcppArmadillo}{
   The simplest way to get started is to create a skeleton of a package
   using \code{RcppArmadillo}. This can be done conveniently by the
   \code{\link{RcppArmadillo.package.skeleton}}
   function.
-
-  The important steps are
-  \itemize{
-    \item Include the \code{RcppArmadillo.h} header file, which also includes
-    \code{armadillo.h}.
-    \item Import Rcpp, and LinkingTo Rcpp and RcppArmadillo by adding these lines to
-    the DESCRIPTION file:
-
-    \preformatted{
-      Imports: Rcpp (>= 0.11.0)
-      LinkingTo: Rcpp, RcppArmadillo
-    }
-
-    \item Link against the BLAS and LAPACK libraries, by adding this line
-    in the \code{Makevars} and \code{Makevars.win} files:
-    \preformatted{PKG_LIBS = $(LAPACK_LIBS) $(BLAS_LIBS) $(FLIBS) }
-  }
 }
-
-\section{Support}{
-  Please use the Rcpp-devel mailing list on r-forge
-  for questions about RcppArmadillo (subscribe first).
-  \url{https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/rcpp-devel}
-
+\section{Threading}{
+  The Armadillo 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{armadillo_get_number_of_omp+threads()} and
+  \code{armadillo_set_number_of_omp_threads()}. A default value is stored at package startup; it
+  recognises R option value \code{Ncpus} and environment variable
+  \code{OMP_THREAD_LIMIT}.  Additional helper functions
+  \code{armadillo_throttle_cores()} and \code{armadillo_reset_cores()} are
+  available to (temporarily) lower the number of cores uses and to reset to
+  the package default value set at startup.
 }
-
-
 \author{
   For RcppArmadillo: Dirk Eddelbuettel, Romain Francois, Doug Bates and
   Binxiang Ni
@@ -87,9 +66,7 @@
   "RcppArmadillo: Accelerating R with high-performance C++ linear algebra",
   Computational	Statistics and Data Analysis, 2014, 71, March, pages
   1054-1063, \doi{10.1016/j.csda.2013.02.005}.
-)
-
 }
-\keyword{ package }
-\keyword{ programming }
-\keyword{ interface }
+\keyword{package}
+\keyword{programming}
+\keyword{interface}