Fluent builder for creating and configuring thread pools. More...

#include <thread_pool_builder.h>

Collaboration diagram for kcenon::thread::thread_pool_builder:

Public Member Functions
	thread_pool_builder (const std::string &name="thread_pool")
	Constructs a builder with the given pool name.

thread_pool_builder &	with_workers (std::size_t count)
	Sets the number of worker threads.

thread_pool_builder &	with_context (const thread_context &context)
	Sets the thread context for logging and monitoring.

thread_pool_builder &	with_queue (std::shared_ptr< job_queue > queue)
	Sets a custom job queue.

thread_pool_builder &	with_queue_adapter (std::unique_ptr< pool_queue_adapter_interface > adapter)
	Sets a policy-based queue adapter.

thread_pool_builder &	with_circuit_breaker (const circuit_breaker_config &config={})
	Adds circuit breaker protection.

thread_pool_builder &	with_circuit_breaker (std::shared_ptr< circuit_breaker > cb)
	Adds circuit breaker with an existing circuit breaker instance.

thread_pool_builder &	with_autoscaling (const autoscaling_policy &config={})
	Enables autoscaling with the specified policy.

thread_pool_builder &	with_work_stealing ()
	Enables work-stealing with default configuration.

thread_pool_builder &	with_work_stealing (const worker_policy &config)
	Enables work-stealing with custom configuration.

thread_pool_builder &	with_diagnostics ()
	Enables diagnostics for the pool.

thread_pool_builder &	with_enhanced_metrics ()
	Enables enhanced metrics collection.

thread_pool_builder &	with_policy (std::unique_ptr< pool_policy > policy)
	Adds a custom policy to the pool.

std::shared_ptr< thread_pool >	build ()
	Builds and returns the configured thread pool.

std::shared_ptr< thread_pool >	build_and_start ()
	Builds the pool and starts it immediately.

Private Member Functions
void	reset ()

Private Attributes
std::string	name_

std::size_t	worker_count_ {0}

thread_context	context_

std::shared_ptr< job_queue >	custom_queue_

std::unique_ptr< pool_queue_adapter_interface >	queue_adapter_

std::vector< std::unique_ptr< pool_policy > >	policies_

bool	enable_diagnostics_ {false}

bool	enable_enhanced_metrics_ {false}

std::optional< circuit_breaker_config >	circuit_breaker_config_

std::shared_ptr< circuit_breaker >	shared_circuit_breaker_

std::optional< autoscaling_policy >	autoscaling_config_

std::optional< worker_policy >	work_stealing_config_

Detailed Description

Fluent builder for creating and configuring thread pools.

The thread_pool_builder provides a fluent API for constructing thread pools with various configuration options. This pattern improves readability and makes configuration immutable until the pool is built.

Design Principles

Fluent Interface: All with_*() methods return *this for chaining
Immutable Configuration: Settings are accumulated before building
Sensible Defaults: Unconfigured options use reasonable defaults
Policy Composition: Multiple policies can be combined

Usage Example

// Basic usage
auto pool = thread_pool_builder("my_pool")
    .with_workers(8)
    .build();
 
// With policies
auto pool = thread_pool_builder("resilient_pool")
    .with_workers(4)
    .with_circuit_breaker(circuit_breaker_config{
        .failure_threshold = 5,
        .open_duration = std::chrono::seconds{30}
    })
    .with_autoscaling(autoscaling_policy{
        .min_workers = 2,
        .max_workers = 16,
        .scaling_mode = autoscaling_policy::mode::automatic
    })
    .with_work_stealing()
    .build();
 
pool->start();

See also: thread_pool; circuit_breaker_policy; autoscaling_pool_policy; work_stealing_pool_policy

Definition at line 77 of file thread_pool_builder.h.

Constructor & Destructor Documentation

◆ thread_pool_builder()

kcenon::thread::thread_pool_builder::thread_pool_builder ( const std::string & name = "thread_pool" )

explicit

Constructs a builder with the given pool name.

Parameters

name	Name/title for the thread pool.

The name is used for identification, logging, and debugging.

Definition at line 9 of file thread_pool_builder.cpp.

        : name_(name)
        , worker_count_(0)
        , context_()
        , enable_diagnostics_(false)
        , enable_enhanced_metrics_(false)
    {
    }

Member Function Documentation

◆ build()

std::shared_ptr< thread_pool > kcenon::thread::thread_pool_builder::build ( )

nodiscard

Builds and returns the configured thread pool.

Returns: Shared pointer to the constructed thread pool.

After calling build(), the builder is reset and can be reused to build another pool with different settings.

Note: The pool is NOT started automatically. Call pool->start() to begin processing jobs.

Definition at line 98 of file thread_pool_builder.cpp.

    {
        std::shared_ptr<thread_pool> pool;
 
        if (queue_adapter_)
        {
            pool = std::make_shared<thread_pool>(name_, std::move(queue_adapter_), context_);
        }
        else if (custom_queue_)
        {
            pool = std::make_shared<thread_pool>(name_, custom_queue_, context_);
        }
        else
        {
            pool = std::make_shared<thread_pool>(name_, context_);
        }
 
        std::size_t worker_count = worker_count_;
        if (worker_count == 0)
        {
            worker_count = std::thread::hardware_concurrency();
            if (worker_count == 0)
            {
                worker_count = 4;
            }
        }
 
        for (std::size_t i = 0; i < worker_count; ++i)
        {
            auto worker = std::make_unique<thread_worker>(true, context_);
            worker->set_job_queue(pool->get_job_queue());
            pool->enqueue(std::move(worker));
        }
 
        if (circuit_breaker_config_.has_value())
        {
            auto cb_policy = std::make_unique<circuit_breaker_policy>(
                circuit_breaker_config_.value());
            pool->add_policy(std::move(cb_policy));
        }
        else if (shared_circuit_breaker_)
        {
            auto cb_policy = std::make_unique<circuit_breaker_policy>(
                shared_circuit_breaker_);
            pool->add_policy(std::move(cb_policy));
        }
 
        if (autoscaling_config_.has_value())
        {
            auto as_policy = std::make_unique<autoscaling_pool_policy>(
                *pool, autoscaling_config_.value());
            pool->add_policy(std::move(as_policy));
        }
 
        if (work_stealing_config_.has_value())
        {
            auto ws_policy = std::make_unique<work_stealing_pool_policy>(
                work_stealing_config_.value());
            pool->add_policy(std::move(ws_policy));
        }
 
        for (auto& policy : policies_)
        {
            pool->add_policy(std::move(policy));
        }
 
        if (enable_enhanced_metrics_)
        {
            pool->set_enhanced_metrics_enabled(true);
        }
 
        if (enable_diagnostics_)
        {
            (void)pool->diagnostics();
        }
 
        reset();
 
        return pool;
    }

References autoscaling_config_, circuit_breaker_config_, context_, custom_queue_, enable_diagnostics_, enable_enhanced_metrics_, name_, policies_, queue_adapter_, reset(), shared_circuit_breaker_, work_stealing_config_, and worker_count_.

Referenced by build_and_start().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ build_and_start()

std::shared_ptr< thread_pool > kcenon::thread::thread_pool_builder::build_and_start ( )

nodiscard

Builds the pool and starts it immediately.

Returns: Shared pointer to the started thread pool.

Convenience method equivalent to:

auto pool = builder.build();
pool->start();
return pool;

Definition at line 179 of file thread_pool_builder.cpp.

    {
        auto pool = build();
        pool->start();
        return pool;
    }

References build().

Referenced by kcenon::thread::event_bus::event_bus().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ reset()

void kcenon::thread::thread_pool_builder::reset ( )

private

Definition at line 186 of file thread_pool_builder.cpp.

    {
        name_ = "thread_pool";
        worker_count_ = 0;
        context_ = thread_context();
        custom_queue_.reset();
        queue_adapter_.reset();
        policies_.clear();
        enable_diagnostics_ = false;
        enable_enhanced_metrics_ = false;
        circuit_breaker_config_.reset();
        shared_circuit_breaker_.reset();
        autoscaling_config_.reset();
        work_stealing_config_.reset();
    }

References autoscaling_config_, circuit_breaker_config_, context_, custom_queue_, enable_diagnostics_, enable_enhanced_metrics_, name_, policies_, queue_adapter_, shared_circuit_breaker_, work_stealing_config_, and worker_count_.

Referenced by build().

Here is the caller graph for this function:

◆ with_autoscaling()

thread_pool_builder & kcenon::thread::thread_pool_builder::with_autoscaling ( const autoscaling_policy & config = {} )

Enables autoscaling with the specified policy.

Parameters

config Autoscaling policy configuration.

Returns: Reference to this builder for chaining.

The autoscaler automatically adjusts worker count based on load metrics (utilization, queue depth, latency).

See also: autoscaling_policy; autoscaling_pool_policy

Definition at line 59 of file thread_pool_builder.cpp.

    {
        autoscaling_config_ = config;
        return *this;
    }

References autoscaling_config_.

◆ with_circuit_breaker() [1/2]

thread_pool_builder & kcenon::thread::thread_pool_builder::with_circuit_breaker ( const circuit_breaker_config & config = {} )

Adds circuit breaker protection.

Parameters

config Circuit breaker configuration.

Returns: Reference to this builder for chaining.

The circuit breaker monitors job failures and automatically opens when a threshold is exceeded, preventing cascading failures.

See also: circuit_breaker_config; circuit_breaker_policy

Definition at line 43 of file thread_pool_builder.cpp.

    {
        circuit_breaker_config_ = config;
        shared_circuit_breaker_.reset();
        return *this;
    }

References circuit_breaker_config_, and shared_circuit_breaker_.

◆ with_circuit_breaker() [2/2]

thread_pool_builder & kcenon::thread::thread_pool_builder::with_circuit_breaker ( std::shared_ptr< circuit_breaker > cb )

Adds circuit breaker with an existing circuit breaker instance.

Parameters

cb	Shared circuit breaker for multiple pools.

Returns: Reference to this builder for chaining.

Use this to share a circuit breaker across multiple pools.

Definition at line 51 of file thread_pool_builder.cpp.

    {
        shared_circuit_breaker_ = std::move(cb);
        circuit_breaker_config_.reset();
        return *this;
    }

References circuit_breaker_config_, and shared_circuit_breaker_.

◆ with_context()

thread_pool_builder & kcenon::thread::thread_pool_builder::with_context ( const thread_context & context )

Sets the thread context for logging and monitoring.

Parameters

context Thread context with logger and monitoring services.

Returns: Reference to this builder for chaining.

Definition at line 24 of file thread_pool_builder.cpp.

    {
        context_ = context;
        return *this;
    }

References context_.

◆ with_diagnostics()

thread_pool_builder & kcenon::thread::thread_pool_builder::with_diagnostics ( )

Enables diagnostics for the pool.

Returns: Reference to this builder for chaining.

Diagnostics provide thread dumps, job inspection, and bottleneck detection capabilities.

Definition at line 80 of file thread_pool_builder.cpp.

    {
        enable_diagnostics_ = true;
        return *this;
    }

References enable_diagnostics_.

◆ with_enhanced_metrics()

thread_pool_builder & kcenon::thread::thread_pool_builder::with_enhanced_metrics ( )

Enables enhanced metrics collection.

Returns: Reference to this builder for chaining.

Enhanced metrics include latency histograms, percentiles, and sliding window throughput tracking.

Definition at line 86 of file thread_pool_builder.cpp.

    {
        enable_enhanced_metrics_ = true;
        return *this;
    }

References enable_enhanced_metrics_.

◆ with_policy()

thread_pool_builder & kcenon::thread::thread_pool_builder::with_policy ( std::unique_ptr< pool_policy > policy )

Adds a custom policy to the pool.

Parameters

policy Custom pool policy.

Returns: Reference to this builder for chaining.

Use this to add custom policies that implement pool_policy.

See also: pool_policy

Definition at line 92 of file thread_pool_builder.cpp.

    {
        policies_.push_back(std::move(policy));
        return *this;
    }

References policies_.

◆ with_queue()

thread_pool_builder & kcenon::thread::thread_pool_builder::with_queue ( std::shared_ptr< job_queue > queue )

Sets a custom job queue.

Parameters

queue Custom job queue implementation.

Returns: Reference to this builder for chaining.

Use this to inject specialized queues like backpressure_job_queue.

Definition at line 30 of file thread_pool_builder.cpp.

    {
        custom_queue_ = std::move(queue);
        return *this;
    }

References custom_queue_.

◆ with_queue_adapter()

thread_pool_builder & kcenon::thread::thread_pool_builder::with_queue_adapter ( std::unique_ptr< pool_queue_adapter_interface > adapter )

Sets a policy-based queue adapter.

Parameters

adapter Queue adapter for policy_queue.

Returns: Reference to this builder for chaining.

Use this for the new policy-based queue system.

Definition at line 36 of file thread_pool_builder.cpp.

    {
        queue_adapter_ = std::move(adapter);
        return *this;
    }

References queue_adapter_.

◆ with_work_stealing() [1/2]

thread_pool_builder & kcenon::thread::thread_pool_builder::with_work_stealing ( )

Enables work-stealing with default configuration.

Returns: Reference to this builder for chaining.

Work-stealing enables idle workers to steal jobs from busy workers, improving load balancing and throughput.

See also: work_stealing_pool_policy

Definition at line 66 of file thread_pool_builder.cpp.

    {
        worker_policy config;
        config.enable_work_stealing = true;
        work_stealing_config_ = config;
        return *this;
    }

References kcenon::thread::worker_policy::enable_work_stealing, and work_stealing_config_.

◆ with_work_stealing() [2/2]

thread_pool_builder & kcenon::thread::thread_pool_builder::with_work_stealing ( const worker_policy & config )

Enables work-stealing with custom configuration.

Parameters

config Worker policy with work-stealing settings.

Returns: Reference to this builder for chaining.

See also: worker_policy; work_stealing_pool_policy

Definition at line 74 of file thread_pool_builder.cpp.

    {
        work_stealing_config_ = config;
        return *this;
    }

References work_stealing_config_.

◆ with_workers()

thread_pool_builder & kcenon::thread::thread_pool_builder::with_workers ( std::size_t count )

Sets the number of worker threads.

Parameters

count Number of workers to create.

Returns: Reference to this builder for chaining.

If not specified, defaults to std::thread::hardware_concurrency().

Definition at line 18 of file thread_pool_builder.cpp.

    {
        worker_count_ = count;
        return *this;
    }

References worker_count_.

Referenced by kcenon::thread::event_bus::event_bus().

Here is the caller graph for this function:

Member Data Documentation

◆ autoscaling_config_

std::optional<autoscaling_policy> kcenon::thread::thread_pool_builder::autoscaling_config_

private

Definition at line 248 of file thread_pool_builder.h.

Referenced by build(), reset(), and with_autoscaling().

◆ circuit_breaker_config_

std::optional<circuit_breaker_config> kcenon::thread::thread_pool_builder::circuit_breaker_config_

private

Definition at line 246 of file thread_pool_builder.h.

Referenced by build(), reset(), with_circuit_breaker(), and with_circuit_breaker().

◆ context_

thread_context kcenon::thread::thread_pool_builder::context_

private

Definition at line 239 of file thread_pool_builder.h.

Referenced by build(), reset(), and with_context().

◆ custom_queue_

std::shared_ptr<job_queue> kcenon::thread::thread_pool_builder::custom_queue_

private

Definition at line 240 of file thread_pool_builder.h.

Referenced by build(), reset(), and with_queue().

◆ enable_diagnostics_

bool kcenon::thread::thread_pool_builder::enable_diagnostics_ {false}

private

Definition at line 243 of file thread_pool_builder.h.

243{false};

Referenced by build(), reset(), and with_diagnostics().

◆ enable_enhanced_metrics_

bool kcenon::thread::thread_pool_builder::enable_enhanced_metrics_ {false}

private

Definition at line 244 of file thread_pool_builder.h.

244{false};

Referenced by build(), reset(), and with_enhanced_metrics().

◆ name_

std::string kcenon::thread::thread_pool_builder::name_

private

Definition at line 237 of file thread_pool_builder.h.

Referenced by build(), and reset().

◆ policies_

std::vector<std::unique_ptr<pool_policy> > kcenon::thread::thread_pool_builder::policies_

private

Definition at line 242 of file thread_pool_builder.h.

Referenced by build(), reset(), and with_policy().

◆ queue_adapter_

std::unique_ptr<pool_queue_adapter_interface> kcenon::thread::thread_pool_builder::queue_adapter_

private

Definition at line 241 of file thread_pool_builder.h.

Referenced by build(), reset(), and with_queue_adapter().

◆ shared_circuit_breaker_

std::shared_ptr<circuit_breaker> kcenon::thread::thread_pool_builder::shared_circuit_breaker_

private

Definition at line 247 of file thread_pool_builder.h.

Referenced by build(), reset(), with_circuit_breaker(), and with_circuit_breaker().

◆ work_stealing_config_

std::optional<worker_policy> kcenon::thread::thread_pool_builder::work_stealing_config_

private

Definition at line 249 of file thread_pool_builder.h.

Referenced by build(), reset(), with_work_stealing(), and with_work_stealing().

◆ worker_count_

std::size_t kcenon::thread::thread_pool_builder::worker_count_ {0}

private

Definition at line 238 of file thread_pool_builder.h.

238{0};

Referenced by build(), reset(), and with_workers().

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

include/kcenon/thread/core/thread_pool_builder.h
src/impl/thread_pool/thread_pool_builder.cpp

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Design Principles

Usage Example

Constructor & Destructor Documentation

◆ thread_pool_builder()

Member Function Documentation

◆ build()

◆ build_and_start()

◆ reset()

◆ with_autoscaling()

◆ with_circuit_breaker() [1/2]

◆ with_circuit_breaker() [2/2]

◆ with_context()

◆ with_diagnostics()

◆ with_enhanced_metrics()

◆ with_policy()

◆ with_queue()

◆ with_queue_adapter()

◆ with_work_stealing() [1/2]

◆ with_work_stealing() [2/2]

◆ with_workers()

Member Data Documentation

◆ autoscaling_config_

◆ circuit_breaker_config_

◆ context_

◆ custom_queue_

◆ enable_diagnostics_

◆ enable_enhanced_metrics_

◆ name_

◆ policies_

◆ queue_adapter_

◆ shared_circuit_breaker_

◆ work_stealing_config_

◆ worker_count_