Improve TBB integration: auto-detection, runtime check, and graceful fallback

[dcasbioinfo]

Hi qs2 team,
First of all, thank you for your excellent work! This package has become a core part of my daily workflow. I'd like to suggest a usability enhancement related to TBB support that could improve the installation experience and runtime transparency - especially for users working in automated environments (like myself).

Current situation
To enable TBB-based multithreading, users currently need to:

• Ensure the TBB library is installed on their system (Linux/macOS),

• Remember to manually pass --with-TBB at install time, and avoid using install.packages() or similar functions or automation layers, as they don’t provide a reliable way to pass custom configure flags such as --with-TBB.

• And after installation, there's no built-in way to confirm whether TBB support was actually enabled.

In other words, these manual steps interrupt an otherwise seamless workflow.

*** Suggested improvements ***

• Automatic detection during install
  It would be helpful if the configure script could check for TBB using pkg-config (on Linux) or brew (on macOS), and enable support by default when available. If TBB is not present, it could gracefully fall back to single-threaded mode without errors.

• Silent runtime check
  Upon package load, it could expose an internal flag accessible for example via qs2::qopt("tbb_enabled"). This would let scripts or pipelines verify multithreading support without triggering warnings or requiring indirect checks.

• Runtime fallback
  Additionally, if a user explicitly requests multiple threads in an environment where TBB support is disabled, the package could silently fall back to single-threaded execution. In this case, rather than throwing an error, it could issue a clear warning informing the user that multithreading is not available and execution will proceed using a single core. This avoids unnecessary runtime failures while still making the limitation visible.

Thanks again for all your work on qs2!

P.S. Automatic detection during installation could also be useful for AVX2 support!

[bshor]

I love and use qs2 in my daily workflow as well.

I have found, outside of Windows where multithreading is automatically available in the binary, setting things up on Linux and Mac is a big pain. I often have to try several times, restart R/Rstudio, etc. Totally outside the usual workflow of using "install.packages".

That said, the package is so useful, I'm willing to keep doing it! But it's a bit of a barrier to entry for others.

[traversc]

Great points and I agree completely that there is a barrier. However linking to TBB by itself causes issues on several CRAN test machines, so it is not straightforward to "enable by default".

I plan to work on it but it might take a little time to get the configuration right.

For now, there are two things that could make it easier for you.

1. You don't need TBB installed on system only install.packages("RcppParallel") which gives access to the TBB library.
2. You can check whether TBB is enabled with qs2:::check_TBB which returns TRUE if qs2 was compiled with TBB.

[traversc]

The latest version falls back to nthreads = 1 if not compiled with TBB, rather than producing an error.

Still unsure whether the tbb::flow library used for multithreading will pass CRAN checks.

[bshor]

I'm having a new problem with qs2 0.1.6 and TBB on MacOS and on Linux.

I installed qs2 by compiling from source with "--with-TBB" (Mac) and the "--with-TBB --with-simd=AVX2" (Linux) arguments as per the instructions. But now when I save or read with nthreads > 1 on either system, I get the following error:

Warning message:
In qs2::qs_read(mpath, nthreads = 8) :
  nthreads > 1 requested but TBB not available; using nthreads = 1

This does not happen with qs2 0.1.5.

[traversc]

@bshor Not able to reproduce.

If you already had 0.1.6 installed, try installing with force=TRUE e.g.

remotes::install_cran("qs2", type = "source", configure.args = "--with-TBB", force = TRUE)

[bshor]

Still the same problem on Linux (running CachyOS and latest kernel, fully updated). Does the compilation messages tell you anything?

> remove.packages("qs2", lib = "~/R/x86_64-pc-linux-gnu-library/4.5")
> sys <- Sys.info()[["sysname"]]
> if (sys == "Windows") install.packages("qs2") else remotes::install_cran(
+   "qs2", type = "source", force = TRUE,
+   configure.args = switch(sys,
+                           Linux  = "--with-TBB --with-simd=AVX2",
+                           Darwin = "--with-TBB",
+                           stop("Unsupported OS")
+   )
+ )
Installing 1 packages: qs2
Installing package into ‘/home/boris/R/x86_64-pc-linux-gnu-library/4.5’
(as ‘lib’ is unspecified)
trying URL 'https://cran.rstudio.com/src/contrib/qs2_0.1.6.tar.gz'
Content type 'application/x-gzip' length 964743 bytes (942 KB)
==================================================
downloaded 942 KB

* installing *source* package ‘qs2’ ...
** this is package ‘qs2’ version ‘0.1.6’
** package ‘qs2’ successfully unpacked and MD5 sums checked
** using staged installation
checking for pkg-config... /usr/bin/pkg-config
checking whether the C++ compiler works... yes
checking for C++ compiler default output file name... a.out
checking for suffix of executables... 
checking whether we are cross compiling... no
checking for suffix of object files... o
checking whether we are using the GNU C++ compiler... yes
checking whether g++ -std=gnu++17 accepts -g... yes
C++ compiler: g++ -std=gnu++17
zstd 1.5.7 library detected -- skipping zstd compilation
Fixed blocksize
Using TBB
Does not require -latomic flag
Using AVX2
configure: creating ./config.status
config.status: creating src/Makevars
** libs
using C++ compiler: ‘g++ (GCC) 15.2.1 20251112’
g++ -std=gnu++17 -I"/usr/include/R/" -DNDEBUG -DRCPP_USE_UNWIND_PROTECT -DRCPP_NO_RTTI -DRCPP_NO_SUGAR -I../inst/include -I.  -mavx2  -DIS_UTF8_LOCALE=1 -I'/home/boris/R/x86_64-pc-linux-gnu-library/4.5/Rcpp/include' -I'/home/boris/R/x86_64-pc-linux-gnu-library/4.5/stringfish/include' -I'/home/boris/R/x86_64-pc-linux-gnu-library/4.5/RcppParallel/include' -I/usr/local/include    -fpic  -march=x86-64 -mtune=generic -O2 -pipe -fno-plt -fexceptions         -Wp,-D_FORTIFY_SOURCE=3 -Wformat -Werror=format-security         -fstack-clash-protection -fcf-protection         -fno-omit-frame-pointer -mno-omit-leaf-frame-pointer -Wp,-D_GLIBCXX_ASSERTIONS -g -ffile-prefix-map=/build/r/src=/usr/src/debug/r -flto=auto -ffat-lto-objects   -c RcppExports.cpp -o RcppExports.o
g++ -std=gnu++17 -I"/usr/include/R/" -DNDEBUG -DRCPP_USE_UNWIND_PROTECT -DRCPP_NO_RTTI -DRCPP_NO_SUGAR -I../inst/include -I.  -mavx2  -DIS_UTF8_LOCALE=1 -I'/home/boris/R/x86_64-pc-linux-gnu-library/4.5/Rcpp/include' -I'/home/boris/R/x86_64-pc-linux-gnu-library/4.5/stringfish/include' -I'/home/boris/R/x86_64-pc-linux-gnu-library/4.5/RcppParallel/include' -I/usr/local/include    -fpic  -march=x86-64 -mtune=generic -O2 -pipe -fno-plt -fexceptions         -Wp,-D_FORTIFY_SOURCE=3 -Wformat -Werror=format-security         -fstack-clash-protection -fcf-protection         -fno-omit-frame-pointer -mno-omit-leaf-frame-pointer -Wp,-D_GLIBCXX_ASSERTIONS -g -ffile-prefix-map=/build/r/src=/usr/src/debug/r -flto=auto -ffat-lto-objects   -c qx_functions.cpp -o qx_functions.o
In file included from /home/boris/R/x86_64-pc-linux-gnu-library/4.5/RcppParallel/include/tbb/internal/_concurrent_unordered_impl.h:37,
                 from /home/boris/R/x86_64-pc-linux-gnu-library/4.5/RcppParallel/include/tbb/concurrent_unordered_set.h:23,
                 from /home/boris/R/x86_64-pc-linux-gnu-library/4.5/RcppParallel/include/RcppParallel/TBB.h:11,
                 from /home/boris/R/x86_64-pc-linux-gnu-library/4.5/RcppParallel/include/RcppParallel.h:24,
                 from qx_functions.cpp:1:
/home/boris/R/x86_64-pc-linux-gnu-library/4.5/RcppParallel/include/tbb/internal/../atomic.h: In instantiation of ‘tbb::atomic<T>& tbb::internal::as_atomic(T&) [with T = long unsigned int]’:
/home/boris/R/x86_64-pc-linux-gnu-library/4.5/RcppParallel/include/tbb/tbb_thread.h:251:29:   required from here
  251 |             return as_atomic(location.my_id).compare_and_swap(value.my_id, comparand.my_id);
      |                    ~~~~~~~~~^~~~~~~~~~~~~~~~
/home/boris/R/x86_64-pc-linux-gnu-library/4.5/RcppParallel/include/tbb/internal/../atomic.h:544:12: warning: casting ‘long unsigned int’ to ‘tbb::atomic<long unsigned int>&’ does not use ‘constexpr tbb::atomic<long unsigned int>::atomic(long unsigned int)’ [-Wcast-user-defined]
  544 |     return (atomic<T>&)t;
      |            ^~~~~~~~~~~~~
g++ -std=gnu++17 -shared -L/usr/lib64/R/lib -Wl,-O1 -Wl,--sort-common -Wl,--as-needed -Wl,-z,relro -Wl,-z,now -Wl,-z,pack-relative-relocs -flto=auto -o qs2.so RcppExports.o qx_functions.o -L. -lzstd -L/usr/lib64/R/lib -lR
installing to /home/boris/R/x86_64-pc-linux-gnu-library/4.5/00LOCK-qs2/00new/qs2/libs
** R
** data
*** moving datasets to lazyload DB
** inst
** byte-compile and prepare package for lazy loading
** help
*** installing help indices
** building package indices
** installing vignettes
** testing if installed package can be loaded from temporary location
** checking absolute paths in shared objects and dynamic libraries
** testing if installed package can be loaded from final location
** testing if installed package keeps a record of temporary installation path
* DONE (qs2)

Notice when it is compiling it does recognize TBB and AVX! But when I try reading ...

qs2::qs_read(mpath, nthreads = 8); toc()
Warning message:
In qs2::qs_read(mpath, nthreads = 8) :
  nthreads > 1 requested but TBB not available; using nthreads = 1

[traversc]

This line here is lacking any RcppParallel compilation flags

g++ -std=gnu++17 -shared -L/usr/lib64/R/lib -Wl,-O1 -Wl,--sort-common -Wl,--as-needed -Wl,-z,relro -Wl,-z,now -Wl,-z,pack-relative-relocs -flto=auto -o qs2.so RcppExports.o qx_functions.o -L. -lzstd -L/usr/lib64/R/lib -lR

The Makevars file has this line below to pull in RcppParallel/TBB flags

$(shell ${R_HOME}/bin/Rscript -e "RcppParallel::RcppParallelLibs()")

What is the output of RcppParallel::RcppParallelLibs()?

Do you have any startup scripts that are used during Rscript?

Possibly an old version or misconfigured version of RcppParallel?

Other than that, I'm not sure what the issue could be. If you can make this reproducible on my end (e.g. instructions on reproducing via docker) I could investigate further.

[bshor]

On my Arch Linux setup, I use the Bioconductor Repo to pull in most of my packages, including RcppParallel, on the command line (eg, paru r-rcppparallel). It's usually pretty up-to-date, but sometimes a little late. The version I have is 5.1.11.1-1.

RcppParallel::RcppParallelLibs() returns nothing (!)

I don't have any startup scripts; in my code I load up some packages and define some functions, nothing crazy.

I'm not quite sure how to create a docker for this, so I'll keep investigating. In the meantime, is there a way to return to 0.1.5 if needed?

UPDATE I think I figured it out. I was using pak::pkg_install instead of remotes::install_cran. I'm not getting the error message any more. I'm sorry to have bothered you! The key to figuring this out was RcppParallel::RcppParallelLibs() which returned nothing after using pak, and -ltbb -ltbbmalloc when using remotes. Turns out pak installs a user library version of rcpp-parallel, which screwed everything out. I deleted it, and reinstalled from scratch with remotes.

[traversc]

No worries, glad you got it figured out!

RcppParallel is a tricky dependency. If it's precompiled you're relying on that it was compiled with the correct switches. Its always best to install it from source.

[Roleren]

A lot of packages are now getting deprecation warning on qs (legacy package).

As there is still not way to make sure depending package users get multithreading for qs2.

That means that people are forced to use a worse package, as most read calls on my linux server is 2x slower for qs2 without TBB compared to qs using 5 threads (usually the optimal).

The problem is that other packages can not install with flags from source,
as R description file rules does not allow it.

So there is no way of doing:
remotes::install_cran("qs2", type = "source", configure.args = "--with-TBB --with-simd=AVX2", force = TRUE)

In addition to the hundreds of thousands of files on the server I have to load and save in qs2 format from qs, this will be a nightmare.

[Roleren]

Conclusion for me, to avoid full collapse of dependencies I changed to qs2 and added this to my package .onAttach

.onAttach <- function(libname, pkgname) {
  if (requireNamespace("qs2", quietly = TRUE)) {
    if (isFALSE(qs2:::check_TBB())) {
      packageStartupMessage(
        "qs2 detected without TBB support.\n",
        "For best performance, reinstall with:\n",
        "remotes::install_cran(\"qs2\", type = \"source\", ",
        "configure.args = \"--with-TBB --with-simd=AVX2\", ",
        "force = TRUE)"
      )
    }
  }
}

To remake all qs files to qs2 format I did:

# bplapply with 48 threads, on 81k files, took 2 hours to run ish
callr::r_bg(BiocParallel::bplapply(list.files("~/livemount/Bio_data/", "\\.qs$|\\.covqs$", recursive = TRUE, full.names = TRUE),
                                   function(file) try(qs2::qs_save(qs::qread(file, nthreads = 1), file, nthreads = 1)))
)