ThreadPool - SeqAn API Documentation

# Class ThreadPool
Handles a pool of concurrent std::threads.

Defined in | <seqan/parallel.h>
Signature | `class ThreadPool;`

## Member Function Overview

- `ThreadPool::TThreadPool() = default;, ThreadPool::TThreadPool(ThreadPool const &) = delete;, ThreadPool::TThreadPool(ThreadPool &&) = delete;`
  The constructor.
- `ThreadPool::~ThreadPool()`
  The destructor.

## Interface Function Overview

- `void join(pool);`
  Explicit barrier over the pool.
- `void setCpuAffinity(pool, cpu, scale);`
  Pins the spawned threads in a round-robin fashion.
- `void spawn(pool, callable, ...args);`
  Spawns a new thread and registers it in the thread pool.

## Detailed Description

This is a simple raii-wrapper class to manage a set of `std::threads`.

## Member Functions Detail

### `ThreadPool::TThreadPool() = default; ThreadPool::TThreadPool(ThreadPool const &) = delete; ThreadPool::TThreadPool(ThreadPool &&) = delete;`

The constructor.

Creates a new instance with an empty pool.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `ThreadPool::~ThreadPool()`

Warning.

If threads cannot be joined (e.g. dead lock) the destructor will wait forever.

The destructor.

Safely destroys the thread pool instance by joining all registered threads. This is an implicit barrier for the owning thread.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

## Interface Functions Detail

### `void join(pool);`

Explicit barrier over the pool.

#### Parameters

`pool` | The ThreadPool to be joined.

Allows the user to wait for all registered threads to be finished before the calling thread continues its execution.

#### Data Races

This function is not thread safe. Concurrent invocations of this function for the same `pool` might result in undefined behavior.

### `void setCpuAffinity(pool, cpu, scale);`

Note.

This function uses pthread functions on the native thread handle and is only available for linux platforms. On all other platforms this function is a no-op.

Pins the spawned threads in a round-robin fashion.

#### Parameters

`pool` | The ThreadPool to pin the threads for.
`cpu` | The number of the first cpu to be pinned.
`scale` | A scaling factor to

Iterates over all threads registered in the pool and pins each of them to a cpu in a round-robin fashion. Using `cpu` and `scale` the cpu ids for pinning the threads can be configured dynamically.

#### Possible implementation:

    cpu * scale % std::thread::hardware_concurrency();

#### Data Races

This function is not thread safe. Concurrent invocations of this function for the same `pool` might result in undefined behavior.

### `void spawn(pool, callable, ...args);`

Spawns a new thread and registers it in the thread pool.

#### Parameters

`pool` | The ThreadPool to register the new spawned thread in.
`callable` | A callable object (e.g. functor or function) that should be executed by the spawned thread.
`args` | Any number of arguments passed to the callable object.

Emplaces the thread in the `pool` and associates the thread with the callable by passing the `args` to the callable instance.

#### Data Races

This function is not thread safe. Concurrent invocations of this function for the same `pool` might result in undefined behavior.

#### Dox Sources

    /*!
     * @class ThreadPool
     *
     * @headerfile <seqan/parallel.h>
     *
     * @brief Handles a pool of concurrent <a href="http://en.cppreference.com/w/cpp
     *        /thread/thread">std::threads</a>.
     *
     * @signature class ThreadPool;
     *
     * This is a simple raii-wrapper class to manage a set of <tt>std::threads</tt>.
     *
     * @fn ThreadPool::ThreadPool
     *
     * @brief The constructor.
     *
     * @signature ThreadPool::TThreadPool() = default;
     * @signature ThreadPool::TThreadPool(ThreadPool const &) = delete;
     * @signature ThreadPool::TThreadPool(ThreadPool &&) = delete;
     *
     * Creates a new instance with an empty pool.
     *
     * @fn ThreadPool::~ThreadPool
     *
     * @brief The destructor.
     *
     * @warning If threads cannot be joined (e.g. dead lock) the destructor will
     *          wait forever.
     *
     * @signature ThreadPool::~ThreadPool()
     *
     * Safely destroys the thread pool instance by joining all registered threads.
     * This is an implicit barrier for the owning thread.
     *
     * @fn ThreadPool#spawn
     *
     * @headerfile <seqan/parallel.h>
     *
     * @brief Spawns a new thread and registers it in the thread pool.
     *
     * @signature void spawn(pool, callable, ...args);
     *
     * @param[in,out] pool The @link ThreadPool @endlink to register the new spawned
     *                     thread in.
     * @param[in] callable A callable object (e.g. functor or function) that should
     *                     be executed by the spawned thread.
     * @param args Any number of arguments passed to the callable object.
     *
     * @datarace This function is not thread safe. Concurrent invocations of this
     *           function for the same <tt>pool</tt> might result in undefined
     *           behavior.
     *
     * Emplaces the thread in the <tt>pool</tt> and associates the thread with the
     * callable by passing the <tt>args</tt> to the callable instance.
     *
     * @fn ThreadPool#join
     *
     * @headerfile <seqan/parallel.h>
     *
     * @brief Explicit barrier over the pool.
     *
     * @signature void join(pool);
     *
     * @param[in,out] pool The @link ThreadPool @endlink to be joined.
     *
     * @datarace This function is not thread safe. Concurrent invocations of this
     *           function for the same <tt>pool</tt> might result in undefined
     *           behavior.
     *
     * Allows the user to wait for all registered threads to be finished before the
     * calling thread continues its execution.
     *
     * @fn ThreadPool#setCpuAffinity
     *
     * @headerfile <seqan/parallel.h>
     *
     * @brief Pins the spawned threads in a round-robin fashion.
     *
     * @note This function uses pthread functions on the native thread handle and is
     *       only available for linux platforms. On all other platforms this
     *       function is a no-op.
     *
     * @signature void setCpuAffinity(pool, cpu, scale);
     *
     * @param[in,out] pool The @link ThreadPool @endlink to pin the threads for.
     * @param[in] cpu The number of the first cpu to be pinned.
     * @param[in] scale A scaling factor to
     *
     * @datarace This function is not thread safe. Concurrent invocations of this
     *           function for the same <tt>pool</tt> might result in undefined
     *           behavior.
     *
     * Iterates over all threads registered in the pool and pins each of them to a
     * cpu in a round-robin fashion. Using <tt>cpu</tt> and <tt>scale</tt> the cpu
     * ids for pinning the threads can be configured dynamically.
     *
     * @section Possible implementation:
     *
     * @code{.cpp}
     * cpu * scale % std::thread::hardware_concurrency();
     * @endcode
     */