Static thread pool. More...

#include <piranha/thread_pool.hpp>

Inherits thread_pool_base<>.

Static Public Member Functions
template<typename F , typename... Args>
static enqueue_t< F &&, Args &&... >	enqueue (unsigned n, F &&f, Args &&... args)
	Enqueue task. More...

static unsigned	size ()
	Size. More...

static void	resize (unsigned new_size)
	Change the number of threads. More...

static void	set_binding (bool flag)
	Set the thread binding policy. More...

static bool	get_binding ()
	Get the thread binding policy. More...

template<typename Int , use_threads_enabler< Int > = 0>
static unsigned	use_threads (const Int &work_size, const Int &min_work_per_thread)
	Compute number of threads to use. More...

Detailed Description

template<typename T = void>
class piranha::thread_pool_< T >

Static thread pool.

Note: The template parameter in this class is unused: its only purpose is to prevent the instantiation of the class' methods if they are not explicitly used. Client code should always employ the piranha::thread_pool alias.

This class manages, via a set of static methods, a pool of threads created at program startup. The number of threads created initially is equal to piranha::runtime_info::get_hardware_concurrency(). If the hardware concurrency cannot be determined, the size of the thread pool will be one.

This class provides methods to enqueue arbitray tasks to the threads in the pool, query the size of the pool, resize the pool and configure the thread binding policy. All methods, unless otherwise specified, are thread-safe, and they provide the strong exception safety guarantee.

Definition at line 279 of file thread_pool.hpp.

Member Function Documentation

◆ enqueue()

template<typename T = void>

template<typename F , typename... Args>

static enqueue_t<F &&, Args &&...> piranha::thread_pool_< T >::enqueue	(	unsigned	n,
		F &&	f,
		Args &&...	args
	)

inlinestatic

Enqueue task.

Note

This method is enabled only if:

a nullary wrapper for F(args...) can be created via std::bind() (which requires F and Args to be copy/move constructible, and F(args...) to be a well-formed expression),
the type returned by F(args...) satisfies piranha::is_returnable.

This method will add a task to the n-th thread in the pool. The task is represented by a callable F and its arguments args, which will be copied/moved via an std::bind() wrapper into an execution queue consumed by the thread to which the task is assigned. The return value is an std::future which can be used to retrieve the return value of (or the exception thrown by) the callable.

Parameters

n	index of the thread that will consume the task.
f	callable object representing the task.
args	arguments to `f`.

Returns: an std::future that will store the result of f(args...).

Exceptions

std::invalid_argument	if the thread index is equal to or larger than the current pool size.
std::runtime_error	if a task is being enqueued while the task queue is stopping (e.g., during program shutdown).
unspecified	any exception thrown by: `std::bind()` or the constructor of `std::packaged_task` or `std::function`, threading primitives, memory allocation errors.

Definition at line 322 of file thread_pool.hpp.

◆ get_binding()

template<typename T = void>

static bool piranha::thread_pool_< T >::get_binding ( )

inlinestatic

Get the thread binding policy.

This method returns the flag set by set_binding(). The threads created on program startup are not bound to specific processors/cores.

Returns: a boolean flag representing the active thread binding policy.

Definition at line 434 of file thread_pool.hpp.

◆ resize()

template<typename T = void>

static void piranha::thread_pool_< T >::resize ( unsigned new_size )

inlinestatic

Change the number of threads.

This method will resize the internal pool to contain new_size threads. The method will first wait for the threads to consume all the pending tasks (while forbidding the addition of new tasks), and it will then create a new pool of size new_size.

Parameters

new_size the new size of the pool.

Exceptions

std::invalid_argument	if `new_size` is zero.
unspecified	any exception thrown by: threading primitives, memory allocation errors.

Definition at line 383 of file thread_pool.hpp.

◆ set_binding()

template<typename T = void>

static void piranha::thread_pool_< T >::set_binding ( bool flag )

inlinestatic

Set the thread binding policy.

If flag is true, this method will bind each thread in the pool to a different processor/core via piranha::bind_to_proc(). If flag is false, then this method will unbind the threads in the pool from any processor/core to which they might be bound.

The threads created at program startup are not bound to any specific processor/core. Any error raised by piranha::bind_to_proc() (e.g., because the number of threads in the pool is larger than the number of logical cores or because the thread binding functionality is not available on the platform) is silently ignored.

Parameters

flag	the desired thread binding policy.

Exceptions

unspecified

any exception thrown by:

threading primitives,
memory allocation errors.

Definition at line 416 of file thread_pool.hpp.

◆ size()

template<typename T = void>

static unsigned piranha::thread_pool_< T >::size ( )

inlinestatic

Size.

Returns: the number of threads in the pool.

Definition at line 337 of file thread_pool.hpp.

◆ use_threads()

template<typename T = void>

template<typename Int , use_threads_enabler< Int > = 0>

static unsigned piranha::thread_pool_< T >::use_threads	(	const Int &	work_size,
		const Int &	min_work_per_thread
	)

inlinestatic

Compute number of threads to use.

Note: This function is enabled only if Int is an unsigned integer type or piranha::integer.

This function computes the suggested number of threads to use, given an amount of total work_size units of work and a minimum amount of work units per thread min_work_per_thread.

The returned value will always be 1 if the calling thread belongs to the thread pool; otherwise, a number of threads such that each thread has at least min_work_per_thread units of work to consume will be returned. In any case, the return value is always greater than zero.

Parameters

work_size	total number of work units.
min_work_per_thread	minimum number of work units to be consumed by a thread in the pool.

Returns: the suggested number of threads to be used, always greater than zero.

Exceptions

std::invalid_argument	if `work_size` or `min_work_per_thread` are not strictly positive.
unspecified	any exception thrown by `boost::lexical_cast()`.

Definition at line 460 of file thread_pool.hpp.

The documentation for this class was generated from the following file:

thread_pool.hpp

Static Public Member Functions

Detailed Description

template<typename T = void> class piranha::thread_pool_< T >

Member Function Documentation

◆ enqueue()

◆ get_binding()

◆ resize()

◆ set_binding()

◆ size()

◆ use_threads()

template<typename T = void>
class piranha::thread_pool_< T >