RcppThread::ThreadPool class

Implemenation of the thread pool pattern based on Thread.

Public static functions

static auto globalInstance() -> ThreadPool&: Access to the global thread pool instance.

Constructors, destructors, conversion operators

ThreadPool(): constructs a thread pool with as many workers as there are cores.
ThreadPool(size_t nWorkers) explicit
~ThreadPool() noexcept: destructor joins all threads if possible.

Public functions

void resize(size_t threads)
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 I> void map(F&& f, I&& items)
template<class F> void parallelFor(int begin, int end, F f, size_t nBatches = 0)
template<class F, class I> void parallelForEach(I& items, F f, size_t nBatches = 0)
void wait()
void join(): waits for all jobs to finish.
void setNumThreads(size_t threads)
auto getNumThreads() const -> size_t: gets the number of active threads in the pool.

Function documentation

RcppThread::ThreadPool::ThreadPool(size_t nWorkers) explicit

Parameters
nWorkers	number of worker threads to create; if `nWorkers = 0`, all work pushed to the pool will be done in the main thread.

constructs a thread pool with nWorkers threads.

void RcppThread::ThreadPool::resize(size_t threads)

changes the number of threads in the pool.

template<class F, class... Args>
void RcppThread::ThreadPool::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 thread pool. The function returns void; if a job returns a result, use pushReturn().

template<class F, class... Args>
auto RcppThread::ThreadPool::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 thread pool.

template<class F, class I>
void RcppThread::ThreadPool::map(F&& f, I&& items)

Parameters
f	function to be mapped.
items	an objects containing the items on which `f` shall be mapped; must allow for `auto` loops (i.e., `std::begin(I)`/ `std::end(I)` must be defined).

maps a function on a list of items, possibly running tasks in parallel.

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

Parameters
begin	first index of the loop.
end	the loop runs in the range `[begin, end)`.
f	an object callable as a function (the 'loop body'); typically a lambda.
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 given by:

ThreadPool pool(2);
pool.forIndex(0, 10, [&] (size_t i) {
    x[i] = i;
});

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

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

Parameters
items	an object allowing for `std::begin()`/`std::end()` and whose elements can be accessed by the `[]` operator.
f	a function (the 'loop body').
nBatches	the number of batches to create; the default (0) uses work stealing to distribute tasks.

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

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

The parallel ThreadPool equivalent is

ThreadPool pool(2);
pool.parallelForEach(x, [&] (double& xx) {
    xx *= 2;
});

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

void RcppThread::ThreadPool::wait()

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

void RcppThread::ThreadPool::setNumThreads(size_t threads)

Parameters
threads	the desired number of threads.

sets the number of active threads in the pool.