ThreadPool Class Reference

Fixed-size thread pool for running arbitrary tasks concurrently. More...

#include <threadpool.h>

Collaboration diagram for ThreadPool:

Public Types
enum class	SubmitError { Inactive , Interrupted }
template<class F >
using	Future = std::future< std::invoke_result_t< F > >
template<class R >
using	RangeFuture = Future< std::ranges::range_reference_t< R > >
template<class F >
using	PackagedTask = std::packaged_task< std::invoke_result_t< F >()>

Public Member Functions
	ThreadPool (const std::string &name)
	~ThreadPool ()
void	Start (int num_workers) EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Start worker threads. More...
void	Stop () EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Stop all worker threads and wait for them to exit. More...
template<class F >
util::Expected< Future< F >, SubmitError >	Submit (F &&fn) noexcept EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Enqueues a new task for asynchronous execution. More...
template<std::ranges::sized_range R> requires (!std::is_lvalue_reference_v<R>)
util::Expected< std::vector< RangeFuture< R > >, SubmitError >	Submit (R &&fns) noexcept EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Enqueues a range of tasks for asynchronous execution. More...
bool	ProcessTask () EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Execute a single queued task synchronously. More...
void	Interrupt () EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Stop accepting new tasks and begin asynchronous shutdown. More...
size_t	WorkQueueSize () EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
size_t	WorkersCount () EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)

Private Member Functions
std::queue< std::packaged_task< void()> > m_work_queue	GUARDED_BY (m_mutex)
bool m_interrupt	GUARDED_BY (m_mutex)
std::vector< std::thread > m_workers	GUARDED_BY (m_mutex)
void	WorkerThread () EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)

Private Attributes
std::string	m_name
Mutex	m_mutex
std::condition_variable	m_cv

Detailed Description

Fixed-size thread pool for running arbitrary tasks concurrently.

The thread pool maintains a set of worker threads that consume and execute tasks submitted through Submit(). Once started, tasks can be queued and processed asynchronously until Stop() is called.

Thread-safety and lifecycle

• Start() and Stop() must be called from a controller (non-worker) thread. Calling Stop() from a worker thread will deadlock, as it waits for all workers to join, including the current one.
• Submit() can be called from any thread, including workers. It safely enqueues new work for execution as long as the pool has active workers.
• Interrupt() stops new task submission and lets queued ones drain in the background. Callers can continue other shutdown steps and call Stop() at the end to ensure no remaining tasks are left to execute.
• Stop() prevents further task submission and blocks until all the queued ones are completed.

Definition at line 47 of file threadpool.h.

Member Typedef Documentation

Future

template<class F >

using ThreadPool::Future = std::future<std::invoke_result_t<F> >

Definition at line 161 of file threadpool.h.

PackagedTask

template<class F >

using ThreadPool::PackagedTask = std::packaged_task<std::invoke_result_t<F>()>

Definition at line 167 of file threadpool.h.

RangeFuture

template<class R >

using ThreadPool::RangeFuture = Future<std::ranges::range_reference_t<R> >

Definition at line 164 of file threadpool.h.

Member Enumeration Documentation

SubmitError

enum class ThreadPool::SubmitError

strong

Enumerator
Inactive
Interrupted

Definition at line 155 of file threadpool.h.

Constructor & Destructor Documentation

ThreadPool()

ThreadPool::ThreadPool ( const std::string &  name )

inlineexplicit

Definition at line 90 of file threadpool.h.

~ThreadPool()

ThreadPool::~ThreadPool ( )

inline

Definition at line 92 of file threadpool.h.

Here is the call graph for this function:

Member Function Documentation

GUARDED_BY() [1/3]

std::queue< std::packaged_task< void()> > m_work_queue ThreadPool::GUARDED_BY ( m_mutex  )

private

GUARDED_BY() [2/3]

bool m_interrupt ThreadPool::GUARDED_BY ( m_mutex  )

inlineprivate

Definition at line 57 of file threadpool.h.

GUARDED_BY() [3/3]

std::vector< std::thread > m_workers ThreadPool::GUARDED_BY ( m_mutex  )

private

Interrupt()

void ThreadPool::Interrupt ( )

inline

Stop accepting new tasks and begin asynchronous shutdown.

Wakes all worker threads so they can drain the queue and exit. Unlike Stop(), this function does not wait for threads to finish.

Note: The next step in the pool lifecycle is calling Stop(), which releases any dangling resources and resets the pool state for shutdown or restart.

Definition at line 268 of file threadpool.h.

Here is the caller graph for this function:

ProcessTask()

bool ThreadPool::ProcessTask ( )

inline

Execute a single queued task synchronously.

Removes one task from the queue and executes it on the calling thread.

Definition at line 243 of file threadpool.h.

Here is the caller graph for this function:

Start()

void ThreadPool::Start ( int  num_workers )

inline

Start worker threads.

Creates and launches num_workers threads that begin executing tasks from the queue. If the pool is already started, throws.

Must be called from a controller (non-worker) thread.

Definition at line 105 of file threadpool.h.

Here is the call graph for this function:

Here is the caller graph for this function:

Stop()

void ThreadPool::Stop ( )

inline

Stop all worker threads and wait for them to exit.

Sets the interrupt flag, wakes all waiting workers, and joins them. Any remaining tasks in the queue will be processed before returning.

Must be called from a controller (non-worker) thread. Concurrent calls to Start() will be rejected while Stop() is in progress.

Definition at line 128 of file threadpool.h.

Here is the call graph for this function:

Here is the caller graph for this function:

Submit() [1/2]

template<class F >

util::Expected< Future< F >, SubmitError > ThreadPool::Submit ( F &&  fn )

inlinenoexcept

Enqueues a new task for asynchronous execution.

Parameters

fn	Callable to execute asynchronously.

Returns

On success, a future containing fn's result. On failure, an error indicating why the task was rejected:

• SubmitError::Inactive: Pool has no workers (never started or already stopped).
• SubmitError::Interrupted: Pool task acceptance has been interrupted.

Thread-safe: Can be called from any thread, including within the provided 'fn' callable.

Warning

Ignoring the returned future requires guarding the task against uncaught exceptions, as they would otherwise be silently discarded.

Definition at line 184 of file threadpool.h.

Here is the caller graph for this function:

Submit() [2/2]

template<std::ranges::sized_range R>
requires (!std::is_lvalue_reference_v<R>)

util::Expected< std::vector< RangeFuture< R > >, SubmitError > ThreadPool::Submit ( R &&  fns )

inlinenoexcept

Enqueues a range of tasks for asynchronous execution.

Parameters

fns	Callables to execute asynchronously.

Returns

On success, a vector of futures containing each element of fns's result in order. On failure, an error indicating why the range was rejected:

• SubmitError::Inactive: Pool has no workers (never started or already stopped).
• SubmitError::Interrupted: Pool task acceptance has been interrupted.

This is more efficient when submitting many tasks at once, since the queue lock is only taken once internally and all worker threads are notified. For single tasks, Submit() is preferred since only one worker thread is notified.

Thread-safe: Can be called from any thread, including within submitted callables.

Warning

Ignoring the returned futures requires guarding tasks against uncaught exceptions, as they would otherwise be silently discarded.

Definition at line 220 of file threadpool.h.

WorkersCount()

size_t ThreadPool::WorkersCount ( )

inline

Definition at line 279 of file threadpool.h.

Here is the caller graph for this function:

WorkerThread()

void ThreadPool::WorkerThread ( )

inlineprivate

Definition at line 60 of file threadpool.h.

Here is the caller graph for this function:

WorkQueueSize()

size_t ThreadPool::WorkQueueSize ( )

inline

Definition at line 274 of file threadpool.h.

Here is the caller graph for this function:

Member Data Documentation

m_cv

std::condition_variable ThreadPool::m_cv

private

Definition at line 53 of file threadpool.h.

m_mutex

Mutex ThreadPool::m_mutex

private

Definition at line 51 of file threadpool.h.

m_name

std::string ThreadPool::m_name

private

Definition at line 50 of file threadpool.h.

---

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

• src/util/threadpool.h