RcppThread namespace

RcppThread functionality

Classes

class ProgressPrinter: Abstract class for printing progress.
class ProgressCounter: A counter showing progress in percent.
class ProgressBar: A progress bar showing progress in percent.
class RErrPrinter: Safely printing to the R console from threaded code.
class RPrinter: Safely printing to the R console from threaded code.
class UserInterruptException: exception class for user interruptions.
class RMonitor: Singleton class for tracking threads and safe communication.
class Thread: R-friendly version of std::thread.
class ThreadPool: Implemenation of the thread pool pattern based on Thread.

Functions

template<class F> void parallelFor(int begin, int end, F f, size_t nThreads = std::thread::hardware_concurrency(), size_t nBatches = 0)
template<class I, class F> void parallelForEach(I& items, F f, size_t nThreads = std::thread::hardware_concurrency(), size_t nBatches = 0)
template<class F, class... Args> void push(F&& f, Args && ... args)
template<class F, class... Args> auto pushReturn(F&& f, Args && ... args) > -> auto
template<class F, class... Args> auto async(F&& f, Args && ... args) > -> auto
void wait()
void checkUserInterrupt(bool condition = true)
auto isInterrupted(bool condition = true) -> bool

Variables

static RErrPrinter Rcerr: global RPrinter instance called 'Rcerr' (as in Rcpp).
static RPrinter Rcout: global RPrinter instance called 'Rcout' (as in Rcpp).
static std::thread::id mainThreadID: global variable holding id of main thread.

Function documentation

template<class F>
void RcppThread::parallelFor(int begin, int end, F f, size_t nThreads = std::thread::hardware_concurrency(), size_t nBatches = 0)

Parameters
begin	first index of the loop.
end	the loop runs in the range `[begin, end)`.
f	a function (the 'loop body').
nThreads	limits the number of threads used from the global pool.
nBatches	the number of batches to create; the default (0) uses work stealing to distribute tasks.

computes an index-based for loop in parallel batches. Consider the following code:

std::vector<double> x(10);
for (size_t i = 0; i < x.size(); i++) {
    x[i] = i;
}

The parallel equivalent is

parallelFor(0, 10, [&] (size_t i) {
    x[i] = i;
});

The function dispatches to a global thread pool, so it can safely be nested or called multiple times with almost no overhead.

Caution: if the iterations are not independent from another, the tasks need to be synchronized manually (e.g., using mutexes).

template<class I, class F>
void RcppThread::parallelForEach(I& items, F f, size_t nThreads = std::thread::hardware_concurrency(), size_t nBatches = 0)

Parameters
items	an object allowing for `items.size()` and whose elements are accessed by the `[]` operator.
f	a function (the 'loop body').
nThreads	limits the number of threads used from the global pool.
nBatches	the number of batches to create; the default (0) uses work stealing to distribute tasks.

computes a range-based for loop in parallel batches. Consider the following code:

std::vector<double> x(10, 1.0);
for (auto& xx : x) {
    xx *= 2;
}

The parallel equivalent is

parallelFor(x, [&] (double& xx) {
    xx *= 2;
});

The function dispatches to a global thread pool, so it can safely be nested or called multiple times with almost no overhead.

Caution: if the iterations are not independent from another, the tasks need to be synchronized manually (e.g., using mutexes).

template<class F, class... Args>
void RcppThread::push(F&& f, Args && ... args)

Parameters
f	a function taking an arbitrary number of arguments.
args	a comma-seperated list of the other arguments that shall be passed to `f`.

pushes jobs to the global thread pool. The function returns void; if a job returns a result, use async().

template<class F, class... Args>
auto RcppThread::pushReturn(F&& f, Args && ... args) >

Parameters
f	a function taking an arbitrary number of arguments.
args	a comma-seperated list of the other arguments that shall be passed to `f`.
Returns	an `std::shared_future`, where the user can get the result and rethrow exceptions.

pushes jobs returning a value to the global thread pool.

template<class F, class... Args>
auto RcppThread::async(F&& f, Args && ... args) >

Parameters
f	a function taking an arbitrary number of arguments.
args	a comma-seperated list of the other arguments that shall be passed to `f`.
Returns	an `std::shared_future`, where the user can get the result and rethrow exceptions.

pushes jobs returning a value to the global thread pool.

void RcppThread::wait()

waits for all jobs to finish and checks for interruptions, but only from the main thread. Does nothing when called from other threads.

void RcppThread::checkUserInterrupt(bool condition = true)

Parameters
condition	optional; a condition for the check to be executed.

checks for user interruptions, but only if called from main thread. Declared as a friend in RMonitor.

bool RcppThread::isInterrupted(bool condition = true)

Parameters
condition	optional; a condition for the check to be executed.

checks for user interruptions, but only if called from main thread (otherwise returns false). Declared as a friend in RMonitor.