kcenon::thread::numa_thread_pool Class Reference

A NUMA-aware thread pool optimized for Non-Uniform Memory Access architectures. More...

#include <numa_thread_pool.h>

Inheritance diagram for kcenon::thread::numa_thread_pool:

Collaboration diagram for kcenon::thread::numa_thread_pool:

Public Member Functions
	numa_thread_pool (const std::string &thread_title="numa_thread_pool", const thread_context &context=thread_context())
	Constructs a new numa_thread_pool instance.
	numa_thread_pool (const std::string &thread_title, std::shared_ptr< job_queue > custom_queue, const thread_context &context=thread_context())
	Constructs a new numa_thread_pool instance with a custom job queue.
	numa_thread_pool (const std::string &thread_title, std::unique_ptr< pool_queue_adapter_interface > queue_adapter, const thread_context &context=thread_context())
	Constructs a new numa_thread_pool instance with a policy_queue adapter.
	~numa_thread_pool () override=default
	Virtual destructor.
void	configure_numa_work_stealing (const enhanced_work_stealing_config &config)
	Configure NUMA-aware work stealing.
const enhanced_work_stealing_config &	numa_work_stealing_config () const
	Get the current NUMA work-stealing configuration.
work_stealing_stats_snapshot	numa_work_stealing_stats () const
	Get a snapshot of NUMA work-stealing statistics.
const numa_topology &	numa_topology_info () const
	Get the detected NUMA topology.
bool	is_numa_system () const
	Check if the system has NUMA architecture.
void	enable_numa_work_stealing ()
	Enable NUMA-optimized work stealing with default settings.
void	disable_numa_work_stealing ()
	Disable NUMA-aware work stealing.
bool	is_numa_work_stealing_enabled () const
	Check if NUMA work stealing is currently enabled.
Public Member Functions inherited from kcenon::thread::thread_pool
	thread_pool (const std::string &thread_title="thread_pool", const thread_context &context=thread_context())
	Constructs a new thread_pool instance.
	thread_pool (const std::string &thread_title, std::shared_ptr< job_queue > custom_queue, const thread_context &context=thread_context())
	Constructs a new thread_pool instance with a custom job queue.
	thread_pool (const std::string &thread_title, std::unique_ptr< pool_queue_adapter_interface > queue_adapter, const thread_context &context=thread_context())
	Constructs a new thread_pool instance with a policy_queue adapter.
virtual	~thread_pool (void)
	Virtual destructor. Cleans up resources used by the thread pool.
auto	get_ptr (void) -> std::shared_ptr< thread_pool >
	Retrieves a std::shared_ptr to this thread_pool instance.
auto	start (void) -> common::VoidResult
	Starts the thread pool and all associated workers.
auto	get_job_queue (void) -> std::shared_ptr< job_queue >
	Returns the shared job_queue used by this thread pool.
const metrics::ThreadPoolMetrics &	metrics () const noexcept
	Access aggregated runtime metrics (read-only reference).
void	reset_metrics ()
	Reset accumulated metrics.
void	set_enhanced_metrics_enabled (bool enabled)
	Enable or disable enhanced metrics collection.
bool	is_enhanced_metrics_enabled () const
	Check if enhanced metrics is enabled.
const metrics::EnhancedThreadPoolMetrics &	enhanced_metrics () const
	Access enhanced metrics (read-only reference).
metrics::EnhancedSnapshot	enhanced_metrics_snapshot () const
	Get enhanced metrics snapshot.
auto	enqueue (std::unique_ptr< job > &&job) -> common::VoidResult
	Enqueues a new job into the shared job_queue.
auto	enqueue_batch (std::vector< std::unique_ptr< job > > &&jobs) -> common::VoidResult
	Enqueues a batch of jobs into the shared job_queue.
auto	enqueue (std::unique_ptr< thread_worker > &&worker) -> common::VoidResult
	Adds a thread_worker to the thread pool for specialized or additional processing.
auto	enqueue_batch (std::vector< std::unique_ptr< thread_worker > > &&workers) -> common::VoidResult
	Adds a batch of thread_worker objects to the thread pool.
auto	stop (const bool &immediately_stop=false) -> common::VoidResult
	Stops the thread pool and all worker threads.
auto	to_string (void) const -> std::string
	Provides a string representation of this thread_pool.
std::uint32_t	get_pool_instance_id () const
	Get the pool instance id.
void	report_metrics ()
	Collect and report current thread pool metrics.
std::size_t	get_idle_worker_count () const
	Get the number of idle workers.
auto	get_context (void) const -> const thread_context &
	Gets the thread context for this pool.
template<typename F , typename R = std::invoke_result_t<std::decay_t<F>>>
auto	submit (F &&callable, const submit_options &opts={}) -> std::future< R >
template<typename F , typename R = std::invoke_result_t<std::decay_t<F>>>
auto	submit (std::vector< F > &&callables, const submit_options &opts={}) -> std::vector< std::future< R > >
template<typename F , typename R = std::invoke_result_t<std::decay_t<F>>>
auto	submit_wait_all (std::vector< F > &&callables, const submit_options &opts={}) -> std::vector< R >
	Submit a batch and wait for all results.
template<typename F , typename R = std::invoke_result_t<std::decay_t<F>>>
auto	submit_wait_any (std::vector< F > &&callables, const submit_options &opts={}) -> common::Result< R >
	Submit a batch and return first completed result.
auto	is_running () const -> bool
	Check if the thread pool is currently running.
auto	get_pending_task_count () const -> std::size_t
	Get the number of pending tasks in the queue.
auto	check_worker_health (bool restart_failed=true) -> std::size_t
	Check health of all worker threads and restart failed workers.
auto	get_active_worker_count () const -> std::size_t
	Get the current number of active (running) workers.
void	add_policy (std::unique_ptr< pool_policy > policy)
	Add a policy to the pool.
auto	get_policies () const -> const std::vector< std::unique_ptr< pool_policy > > &
	Get all registered policies.
template<typename T = pool_policy>
auto	find_policy (const std::string &name) -> T *
	Find a policy by name.
auto	remove_policy (const std::string &name) -> bool
	Remove a policy by name.
auto	diagnostics () -> diagnostics::thread_pool_diagnostics &
	Get the diagnostics interface for this pool.
auto	diagnostics () const -> const diagnostics::thread_pool_diagnostics &
	Get the diagnostics interface for this pool (const version).
auto	collect_worker_diagnostics () const -> std::vector< diagnostics::thread_info >
	Collects diagnostics information from all workers.

Private Member Functions
void	ensure_topology_detected () const
	Ensure topology is detected.

Private Attributes
numa_topology	cached_topology_
	Cached NUMA topology (detected on construction)
bool	topology_detected_ {false}
	Flag indicating if topology has been detected.
enhanced_work_stealing_config	enhanced_ws_config_
	Enhanced work-stealing configuration.
std::unique_ptr< numa_work_stealer >	numa_work_stealer_
	NUMA-aware work stealer.
worker_policy	worker_policy_
	Worker policy configuration.

Detailed Description

A NUMA-aware thread pool optimized for Non-Uniform Memory Access architectures.

The numa_thread_pool class extends thread_pool with specialized support for NUMA (Non-Uniform Memory Access) architectures. It provides:

• NUMA topology detection and awareness
• NUMA-optimized work stealing (prefer same-node steals)
• Cross-node steal penalty configuration
• NUMA-specific statistics collection

This class is designed for systems where memory access latency varies based on the physical location of CPUs and memory. By preferring work stealing from workers on the same NUMA node, it can significantly improve cache locality and reduce cross-node memory traffic.

When to Use

Use numa_thread_pool when:

• Running on multi-socket servers with NUMA architecture
• Memory-intensive workloads where cache locality matters
• You need to monitor NUMA-specific performance metrics

For single-socket systems or NUMA-unaware workloads, use the base thread_pool class for simpler API and lower overhead.

Usage Example

#include <kcenon/thread/core/numa_thread_pool.h>
 
// Create NUMA-aware pool with default settings
auto pool = std::make_shared<numa_thread_pool>("numa_workers");
 
// Configure NUMA-optimized work stealing
pool->configure_numa_work_stealing(enhanced_work_stealing_config::numa_optimized());
 
// Add workers and start
pool->enqueue(std::make_unique<thread_worker>(true));
pool->start();
 
// Check NUMA topology
const auto& topology = pool->numa_topology();
std::cout << "NUMA nodes: " << topology.node_count() << "\n";
 
// Monitor NUMA performance
auto stats = pool->numa_work_stealing_stats();
std::cout << "Cross-node ratio: " << stats.cross_node_ratio() << "\n";

Migration from thread_pool NUMA methods

If you were using NUMA methods directly on thread_pool, migrate as follows:

// Old (deprecated):
auto pool = std::make_shared<thread_pool>("pool");
pool->set_work_stealing_config(config);  // Deprecated
auto stats = pool->get_work_stealing_stats();  // Deprecated
 
// New (recommended):
auto pool = std::make_shared<numa_thread_pool>("pool");
pool->configure_numa_work_stealing(config);
auto stats = pool->numa_work_stealing_stats();

See also

thread_pool Base class with general thread pool functionality

enhanced_work_stealing_config Configuration for NUMA-aware work stealing

numa_topology System NUMA topology information

Definition at line 93 of file numa_thread_pool.h.

Constructor & Destructor Documentation

numa_thread_pool() [1/3]

kcenon::thread::numa_thread_pool::numa_thread_pool ( const std::string & thread_title = "numa_thread_pool", const thread_context & context = thread_context() )

explicit

Constructs a new numa_thread_pool instance.

Parameters

thread_title	An optional title or identifier for the thread pool (defaults to "numa_thread_pool").
context	Optional thread context for logging and monitoring (defaults to empty context).

The pool automatically detects the system's NUMA topology on construction.

Definition at line 10 of file numa_thread_pool.cpp.

    : thread_pool(thread_title, context) {
    // Eagerly detect topology on construction
    ensure_topology_detected();
}

References ensure_topology_detected().

Here is the call graph for this function:

numa_thread_pool() [2/3]

kcenon::thread::numa_thread_pool::numa_thread_pool	(	const std::string &	thread_title,
		std::shared_ptr< job_queue >	custom_queue,
		const thread_context &	context = thread_context() )

Constructs a new numa_thread_pool instance with a custom job queue.

Parameters

thread_title	A title or identifier for the thread pool.
custom_queue	A custom job queue implementation.
context	Optional thread context for logging and monitoring.

Definition at line 17 of file numa_thread_pool.cpp.

    : thread_pool(thread_title, std::move(custom_queue), context) {
    ensure_topology_detected();
}

References ensure_topology_detected().

Here is the call graph for this function:

numa_thread_pool() [3/3]

kcenon::thread::numa_thread_pool::numa_thread_pool	(	const std::string &	thread_title,
		std::unique_ptr< pool_queue_adapter_interface >	queue_adapter,
		const thread_context &	context = thread_context() )

Constructs a new numa_thread_pool instance with a policy_queue adapter.

Parameters

thread_title	A title or identifier for the thread pool.
queue_adapter	A queue adapter wrapping a policy_queue.
context	Optional thread context for logging and monitoring.

Definition at line 24 of file numa_thread_pool.cpp.

    : thread_pool(thread_title, std::move(queue_adapter), context) {
    ensure_topology_detected();
}

References ensure_topology_detected().

Here is the call graph for this function:

~numa_thread_pool()

kcenon::thread::numa_thread_pool::~numa_thread_pool ( )

overridedefault

Virtual destructor.

Member Function Documentation

configure_numa_work_stealing()

void kcenon::thread::numa_thread_pool::configure_numa_work_stealing

(

const enhanced_work_stealing_config &

config

)

Configure NUMA-aware work stealing.

Parameters

config

The enhanced work-stealing configuration.

This is the primary method for enabling and configuring NUMA-aware work stealing. Use factory methods on enhanced_work_stealing_config for common configurations:

pool->configure_numa_work_stealing(enhanced_work_stealing_config::numa_optimized());

Definition at line 31 of file numa_thread_pool.cpp.

                                                                                               {
    enhanced_ws_config_ = config;
    worker_policy_.enable_work_stealing = config.enabled;
 
    if (config.enabled) {
        if (cached_topology_.node_count() == 0) {
            ensure_topology_detected();
        }
        // Note: Full work stealer setup is done in start() or when workers are added
    }
}

References cached_topology_, kcenon::thread::worker_policy::enable_work_stealing, kcenon::thread::enhanced_work_stealing_config::enabled, enhanced_ws_config_, ensure_topology_detected(), kcenon::thread::numa_topology::node_count(), and worker_policy_.

Referenced by disable_numa_work_stealing(), and enable_numa_work_stealing().

Here is the call graph for this function:

Here is the caller graph for this function:

disable_numa_work_stealing()

void kcenon::thread::numa_thread_pool::disable_numa_work_stealing

(

)

Disable NUMA-aware work stealing.

Reverts to basic work stealing without NUMA awareness.

Definition at line 68 of file numa_thread_pool.cpp.

                                                  {
    enhanced_work_stealing_config config;
    config.enabled = false;
    configure_numa_work_stealing(config);
}

References configure_numa_work_stealing(), and kcenon::thread::enhanced_work_stealing_config::enabled.

Here is the call graph for this function:

enable_numa_work_stealing()

void kcenon::thread::numa_thread_pool::enable_numa_work_stealing

(

)

Enable NUMA-optimized work stealing with default settings.

Convenience method equivalent to:

configure_numa_work_stealing(enhanced_work_stealing_config::numa_optimized());

Definition at line 64 of file numa_thread_pool.cpp.

                                                 {
    configure_numa_work_stealing(enhanced_work_stealing_config::numa_optimized());
}

References configure_numa_work_stealing(), and kcenon::thread::enhanced_work_stealing_config::numa_optimized().

Here is the call graph for this function:

ensure_topology_detected()

void kcenon::thread::numa_thread_pool::ensure_topology_detected ( ) const

private

Ensure topology is detected.

Definition at line 78 of file numa_thread_pool.cpp.

                                                      {
    if (!topology_detected_) {
        cached_topology_ = numa_topology::detect();
        topology_detected_ = true;
    }
}

References cached_topology_, kcenon::thread::numa_topology::detect(), and topology_detected_.

Referenced by configure_numa_work_stealing(), is_numa_system(), numa_thread_pool(), numa_thread_pool(), numa_thread_pool(), and numa_topology_info().

Here is the call graph for this function:

Here is the caller graph for this function:

is_numa_system()

bool kcenon::thread::numa_thread_pool::is_numa_system ( ) const

nodiscard

Check if the system has NUMA architecture.

Returns

true if system has multiple NUMA nodes, false otherwise.

Definition at line 59 of file numa_thread_pool.cpp.

                                            {
    ensure_topology_detected();
    return cached_topology_.is_numa_available();
}

References cached_topology_, ensure_topology_detected(), and kcenon::thread::numa_topology::is_numa_available().

Here is the call graph for this function:

is_numa_work_stealing_enabled()

bool kcenon::thread::numa_thread_pool::is_numa_work_stealing_enabled ( ) const

nodiscard

Check if NUMA work stealing is currently enabled.

Returns

true if NUMA work stealing is enabled.

Definition at line 74 of file numa_thread_pool.cpp.

                                                           {
    return numa_work_stealing_config().enabled && numa_work_stealing_config().numa_aware;
}

References kcenon::thread::enhanced_work_stealing_config::enabled, kcenon::thread::enhanced_work_stealing_config::numa_aware, and numa_work_stealing_config().

Here is the call graph for this function:

numa_topology_info()

const numa_topology & kcenon::thread::numa_thread_pool::numa_topology_info ( ) const

nodiscard

Get the detected NUMA topology.

Returns

Reference to the NUMA topology information.

The topology is detected once and cached. It includes:

• Number of NUMA nodes
• CPU-to-node mapping
• Inter-node distances

Definition at line 54 of file numa_thread_pool.cpp.

                                                                {
    ensure_topology_detected();
    return cached_topology_;
}

References cached_topology_, and ensure_topology_detected().

Here is the call graph for this function:

numa_work_stealing_config()

const enhanced_work_stealing_config & kcenon::thread::numa_thread_pool::numa_work_stealing_config ( ) const

nodiscard

Get the current NUMA work-stealing configuration.

Returns

Reference to the current configuration.

Definition at line 43 of file numa_thread_pool.cpp.

                                                                                       {
    return enhanced_ws_config_;
}

References enhanced_ws_config_.

Referenced by is_numa_work_stealing_enabled().

Here is the caller graph for this function:

numa_work_stealing_stats()

work_stealing_stats_snapshot kcenon::thread::numa_thread_pool::numa_work_stealing_stats ( ) const

nodiscard

Get a snapshot of NUMA work-stealing statistics.

Returns

Non-atomic snapshot of current statistics.

Statistics include:

• Steal attempts and success rate
• Same-node vs cross-node steals
• Batch stealing metrics
• Timing information

Definition at line 47 of file numa_thread_pool.cpp.

                                                                              {
    if (numa_work_stealer_) {
        return numa_work_stealer_->get_stats_snapshot();
    }
    return work_stealing_stats_snapshot{};
}

References numa_work_stealer_.

Member Data Documentation

cached_topology_

numa_topology kcenon::thread::numa_thread_pool::cached_topology_

mutableprivate

Cached NUMA topology (detected on construction)

Definition at line 210 of file numa_thread_pool.h.

Referenced by configure_numa_work_stealing(), ensure_topology_detected(), is_numa_system(), and numa_topology_info().

enhanced_ws_config_

enhanced_work_stealing_config kcenon::thread::numa_thread_pool::enhanced_ws_config_

private

Enhanced work-stealing configuration.

Definition at line 216 of file numa_thread_pool.h.

Referenced by configure_numa_work_stealing(), and numa_work_stealing_config().

numa_work_stealer_

std::unique_ptr<numa_work_stealer> kcenon::thread::numa_thread_pool::numa_work_stealer_

private

NUMA-aware work stealer.

Definition at line 219 of file numa_thread_pool.h.

Referenced by numa_work_stealing_stats().

topology_detected_

bool kcenon::thread::numa_thread_pool::topology_detected_ {false}

mutableprivate

Flag indicating if topology has been detected.

Definition at line 213 of file numa_thread_pool.h.

{false};

Referenced by ensure_topology_detected().

worker_policy_

worker_policy kcenon::thread::numa_thread_pool::worker_policy_

private

Worker policy configuration.

Definition at line 222 of file numa_thread_pool.h.

Referenced by configure_numa_work_stealing().

---

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

• include/kcenon/thread/core/numa_thread_pool.h
• src/impl/thread_pool/numa_thread_pool.cpp