Repository files navigation

Provides R-friendly threading functionality:

• thread safe versions ofRcpp'scheckUserInterrupt(),Rcout, andRcerr,
• an interruptible thread class that otherwise behaves likestd::thread,
• classes for thethread poolpattern and parallel for loopsfor easy and flexible parallelism,
• thread safe progress tracking,
• state-of-the art speed, seebenchmarks.

The library is header-only, platform-independent, and onlyrequires aC++11-compatible compiler.

For a detailed description of its functionality and examples, see the associatedJSS paperor theAPI documentation.

Since then, the followingnew features have been added:

• Printing to the error stream withRcerr.

• Free-standing functions likeparallelFor() now dispatchto a global thread pool that persists for the entire session. Thissignificantly speeds up programs that repeatedly call these functions.

• Faster runtimes due to lock-free work stealing queue and loops (fromquickpool).

• Option to resize a thread pool.

• An R functionRcppThread::detectCores() to determine the number of (logical)cores on your machine.

• C++ classesProgressCounter andProgressBar for tracking progress inlong-running loops.
  Example usage:

  // 20 iterations in loop, update progress every 1 sec  RcppThread::ProgressBarbar(20,1);RcppThread::parallelFor(0,20, [&] (int i) {std::this_thread::sleep_for(std::chrono::milliseconds(200));      bar++;  });

  Output: (just one line that is continuously updated)

  ...Computing: [==========================              ] 65% (~1s remaining)       ...Computing: [========================================] 100% (done)

Release version from CRAN:

install.packages("RcppThread")

Latest development version from github:

# install.packages("devtools")devtools::install_github("tnagler/RcppThread")

Pass"RcppThread" to thedepends argument and"cpp11" to thepluginsargument. For example:

Rcpp::cppFunction('void func() { /* actual code here */ }',depends="RcppThread",plugins="cpp11")

Add

// [[Rcpp::plugins(cpp11)]]// [[Rcpp::depends(RcppThread)]]

before including any headers in your source code.

1. Add the lineCXX_STD = CXX11 to thesrc/Makevars(.win) files of your package.
2. AddRcppThread to theLinkingTo field of yourDESCRIPTION file.

For optimal portability, you might also want to add

PKG_LIBS = `"$(R_HOME)/bin/Rscript" -e "RcppThread::LdFlags()"`

to yoursrc/Makevars (not.win). This adds-latomic/-lpthread flags asnecessary and available.

There are preprocessor options to replace all occurrences ofstd::cout,std::cerr, andstd::thread with calls toRcppThread::Rcout,RcppThread::Rcerr, andRcppThread::Thread(provided that the RcppThread headers are included first). To enable this, use

#define RCPPTHREAD_OVERRIDE_COUT 1    // std::cout override#define RCPPTHREAD_OVERRIDE_CERR 1    // std::cerr override#define RCPPTHREAD_OVERRIDE_THREAD 1  // std::thread override

before including the RcppThread headers.

Nagler, T. (2021). "R-Friendly Multi-Threading in C++."Journal of StatisticalSoftware, Code Snippets,97(1), 1-18.doi: 10.18637/jss.v097.c01