seqan3::detail::execution_handler_parallel Class Reference

Handles the parallel execution of algorithms. More...

#include <seqan3/core/algorithm/detail/execution_handler_parallel.hpp>

Classes
class	internal_state
	An internal state stored on the heap to allow safe move construction/assignment of the class. More...

Public Member Functions
template<std::copy_constructible algorithm_t, std::ranges::input_range algorithm_input_range_t, std::copy_constructible callback_t> requires std::invocable<algorithm_t, std::ranges::range_reference_t<algorithm_input_range_t>, callback_t>
void	bulk_execute (algorithm_t &&algorithm, algorithm_input_range_t &&input_range, callback_t &&callback)
	Asynchronously executes the algorithm for every element of the given input range.
template<std::copy_constructible algorithm_t, typename algorithm_input_t , std::copy_constructible callback_t> requires std::invocable<algorithm_t, algorithm_input_t, callback_t> && (std::is_lvalue_reference_v<algorithm_input_t> || std::move_constructible<algorithm_input_t>)
void	execute (algorithm_t &&algorithm, algorithm_input_t &&input, callback_t &&callback)
	Asynchronously schedules a new algorithm task with the given input and callback.
void	wait ()
	Waits until all submitted algorithm jobs have been completed.
Constructors, destructor and assignment
Instances of this class are not copyable.
	execution_handler_parallel (size_t const thread_count)
	Constructs the execution handler spawning thread_count many threads.
	execution_handler_parallel ()
	Constructs the execution handler spawning 1 thread.
	execution_handler_parallel (execution_handler_parallel const &)=delete
	Deleted.
	execution_handler_parallel (execution_handler_parallel &&)=default
	Defaulted.
execution_handler_parallel &	operator= (execution_handler_parallel const &)=delete
	Deleted.
execution_handler_parallel &	operator= (execution_handler_parallel &&)=default
	Defaulted.
	~execution_handler_parallel ()=default
	Defaulted.

Private Types
using	task_type = std::function< void()>
	The type erased task type.

Private Attributes
std::unique_ptr< internal_state >	state {nullptr}
	Manages the internal state.

Detailed Description

Handles the parallel execution of algorithms.

This execution handler implements a non-blocking execute method. This means a call to seqan3::detail::execution_handler_parallel::execute will invoke the algorithm asynchronously. This handler can be used in combination with the seqan3::detail::algorithm_executor_blocking to invoke the algorithms on the given algorithm input.

Concurrency

This class maintains a thread pool and a concurrent queue to execute the algorithm tasks asynchronously. On construction the active consumer threads are spawned in the thread pool and concurrently start fetching algorithm tasks from the concurrent queue. At the same time only one producer thread is allowed to asynchronously submit new algorithm tasks.

Note

Instances of this class are not copyable.

Warning

This class is only thread-safe in a single producer context. Multiple consumers are allowed. Concurrent invocation of the interfaces are undefined behaviour.

Attention

This class cannot be reused for multiple calls. For this to work, it requires barriers and a queue that can be reopened.

Constructor & Destructor Documentation

execution_handler_parallel() [1/2]

seqan3::detail::execution_handler_parallel::execution_handler_parallel ( size_t const  thread_count )

inline

Constructs the execution handler spawning thread_count many threads.

Parameters

thread_count

The number of threads to spawn.

Spawns thread_count many threads processing the tasks in the queue in parallel.

execution_handler_parallel() [2/2]

seqan3::detail::execution_handler_parallel::execution_handler_parallel ( )

inline

Constructs the execution handler spawning 1 thread.

Why only 1 thread?

This class is not public. It handles the thread pool when, e.g., using the alignment or search algorithms in parallel via the config. This config requires a value (no default), hence the number of threads is always set by the user.

When we use an algorithm in parallel, we also default construct a execution_handler_parallel along the way. If the default is set to use all threads, we have to generate the thread pool and a queue. However, this default constructed execution_handler_parallel is immediately moved away and destructed.

Member Function Documentation

bulk_execute()

template<std::copy_constructible algorithm_t, std::ranges::input_range algorithm_input_range_t, std::copy_constructible callback_t>
requires std::invocable<algorithm_t, std::ranges::range_reference_t<algorithm_input_range_t>, callback_t>

void seqan3::detail::execution_handler_parallel::bulk_execute ( algorithm_t &&  algorithm, algorithm_input_range_t &&  input_range, callback_t &&  callback  )

inline

Asynchronously executes the algorithm for every element of the given input range.

Template Parameters

algorithm_t	The type of the algorithm.
algorithm_input_range_t	The input range type.
callback_t	The type of the callable invoked by the algorithm after generating a new result.

Parameters

[in]	algorithm	The algorithm to invoke.
[in]	input_range	The input range to process asynchronously.
[in]	callback	A callable which will be invoked on each result generated by the algorithm for a given input.

Effectively calls seqan3::detail::execution_handler_parallel::execute on every element of the given input range. For every element, a work task is generated and queued for processing by the threads spawned at the construction of this execution handler. The call blocks until all elements have been processed.

execute()

template<std::copy_constructible algorithm_t, typename algorithm_input_t , std::copy_constructible callback_t>
requires std::invocable<algorithm_t, algorithm_input_t, callback_t> && (std::is_lvalue_reference_v<algorithm_input_t> || std::move_constructible<algorithm_input_t>)

void seqan3::detail::execution_handler_parallel::execute ( algorithm_t &&  algorithm, algorithm_input_t &&  input, callback_t &&  callback  )

inline

Asynchronously schedules a new algorithm task with the given input and callback.

Template Parameters

algorithm_t	The type of the algorithm; must model std::copy_constructible and std::invocable with the given input type as first argument and the callback type as second argument.
algorithm_input_t	The input type to invoke the algorithm with (see below for requirements on this type).
callback_t	The type of the callable invoked by the algorithm after generating a new result; must model std::copy_constructible.

Parameters

[in]	algorithm	The algorithm to invoke.
[in]	input	The input of the algorithm.
[in]	callback	A callable which will be invoked on each result generated by the algorithm.

Inside the function the algorithm and the callback are captured as copies to the sate of a lambda function which wraps the task that is stored on the concurrent queue and asynchronously executed. The algorithm input type, however, is perfectly forwarded if input is a lvalue-reference or moved if it is a rvalue-reference. Accordingly, the algorithm_input_t must either be a lvalue_reference or std::move_constructible.

---

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

• execution_handler_parallel.hpp