dfx::Runtime::ThreadPool Class Reference

Runtime thread pool executing Task instances with priorities and FIFO ordering. More...

#include <dfx-runtime/ThreadPool.hpp>

Public Types
using	MaybeThreadData = std::optional<std::reference_wrapper<ThreadData>>
	Optional reference to mutable thread data.
using	MaybeCThreadData = std::optional<std::reference_wrapper<ThreadData const>>
	Optional reference to immutable thread data.

Public Member Functions
	ThreadPool (std::size_t threadCount=1)
	Construct a thread pool with an initial number of worker threads.
	~ThreadPool ()
	Stop all worker threads and abandon remaining tasks.
void	addThread (std::size_t count=1)
	Add worker threads to the pool.
void	removeThread (std::size_t count=1)
	Remove worker threads from the pool.
std::size_t	threadCount () const noexcept
	Current number of worker threads.
void	pushTask (TaskPtr task)
	Submit a task for execution.
void	pushTasks (std::vector< TaskPtr > tasks)
	Submit multiple tasks for execution.
template<DerivedFromTask T, typename ... Args> requires std::is_constructible_v<T, Args...>
void	emplaceTask (Args &&... args)
	Construct a task in-place and submit it.
MaybeThreadData	threadData ()
	Retrieve the calling thread's ThreadData if it belongs to this pool.
MaybeCThreadData	threadData () const
	Retrieve the calling thread's ThreadData if it belongs to this pool.

Detailed Description

Runtime thread pool executing Task instances with priorities and FIFO ordering.

ThreadPool owns a set of worker threads (std::jthread) that continuously pull Task objects from an internal queue and execute them.

Tasks are scheduled using a priority first policy:

• higher task priority runs first
• among tasks with the same priority, execution is FIFO (first submitted, first executed)

Thread-local runtime data

Each worker thread automatically has an associated ThreadData instance:

• created when the worker thread starts,
• destroyed when the worker thread stops.

This allows tasks to access runtime thread metadata in a thread-independent way, without relying on thread_local storage or global maps.

threadData()

The threadData methods return a reference to the current thread's ThreadData only if the calling thread belongs to this pool. If called from any other thread, they return std::nullopt.

Thread-safety

• Submitting tasks is thread-safe.
• Resizing the pool (adding/removing threads) is thread-safe with respect to task submission, but may block while threads start/stop.

Member Typedef Documentation

MaybeCThreadData

using dfx::Runtime::ThreadPool::MaybeCThreadData = std::optional<std::reference_wrapper<ThreadData const>>

Optional reference to immutable thread data.

MaybeThreadData

using dfx::Runtime::ThreadPool::MaybeThreadData = std::optional<std::reference_wrapper<ThreadData>>

Optional reference to mutable thread data.

Constructor & Destructor Documentation

ThreadPool()

dfx::Runtime::ThreadPool::ThreadPool

(

std::size_t

threadCount = 1

)

Construct a thread pool with an initial number of worker threads.

A value of 0 is not allowed and will throw an exception.

Parameters

threadCount

Number of worker threads to start immediately.

~ThreadPool()

dfx::Runtime::ThreadPool::~ThreadPool

(

)

Stop all worker threads and abandon remaining tasks.

The pool stops its std::jthread workers (cooperative stop via stop tokens). Remaining task if any will not be run and thread will stop as soon as their current task is finished.

Member Function Documentation

addThread()

void dfx::Runtime::ThreadPool::addThread

(

std::size_t

count = 1

)

Add worker threads to the pool.

Each new worker will create its own ThreadData on start.

Parameters

count

Number of threads to create and start.

emplaceTask()

template<DerivedFromTask T, typename ... Args>
requires std::is_constructible_v<T, Args...>

void dfx::Runtime::ThreadPool::emplaceTask ( Args &&... args )

inline

Construct a task in-place and submit it.

Template Parameters

T	Concrete Task type.
Args	Constructor argument types.

Parameters

args	Arguments forwarded to T's constructor.

pushTask()

void dfx::Runtime::ThreadPool::pushTask

(

TaskPtr

task

)

Submit a task for execution.

Parameters

task	Task to enqueue. Must not be null.

pushTasks()

void dfx::Runtime::ThreadPool::pushTasks

(

std::vector< TaskPtr >

tasks

)

Submit multiple tasks for execution.

Parameters

tasks

Tasks to enqueue.

removeThread()

void dfx::Runtime::ThreadPool::removeThread

(

std::size_t

count = 1

)

Remove worker threads from the pool.

There are two important behaviors:

• The pool will never shrink below 1 worker thread. If count would remove too many threads, it is clamped so that at least one worker remains.
• In this function threads are requested to stop but not joined. So it is possible that after calling this function threadCount() still return a value higher than expected.

Parameters

count

Requested number of threads to stop.

threadCount()

std::size_t dfx::Runtime::ThreadPool::threadCount ( ) const

inlinenoexcept

Current number of worker threads.

threadData() [1/2]

MaybeThreadData dfx::Runtime::ThreadPool::threadData

(

)

Retrieve the calling thread's ThreadData if it belongs to this pool.

Returns

Reference to this worker's ThreadData, or std::nullopt if called from a non-pool thread.

threadData() [2/2]

MaybeCThreadData dfx::Runtime::ThreadPool::threadData

(

)

const

Retrieve the calling thread's ThreadData if it belongs to this pool.

Returns

Reference to this worker's ThreadData, or std::nullopt if called from a non-pool thread.

---

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

• lib/dfx-runtime/ThreadPool.hpp