Pool policy that implements work-stealing behavior for load balancing. More...

#include <work_stealing_pool_policy.h>

Inheritance diagram for kcenon::thread::work_stealing_pool_policy:

Collaboration diagram for kcenon::thread::work_stealing_pool_policy:

Public Member Functions
	work_stealing_pool_policy (const worker_policy &config={})
	Constructs a work-stealing policy with the given configuration.

	~work_stealing_pool_policy () override=default
	Destructor.

	work_stealing_pool_policy (const work_stealing_pool_policy &)=delete

work_stealing_pool_policy &	operator= (const work_stealing_pool_policy &)=delete

	work_stealing_pool_policy (work_stealing_pool_policy &&)=delete

work_stealing_pool_policy &	operator= (work_stealing_pool_policy &&)=delete

auto	on_enqueue (job &j) -> common::VoidResult override
	Called before a job is enqueued.

void	on_job_start (job &j) override
	Called when job starts executing.

void	on_job_complete (job &j, bool success, const std::exception *error=nullptr) override
	Called when a job completes.

auto	get_name () const -> std::string override
	Gets the policy name.

auto	is_enabled () const -> bool override
	Checks if the policy is enabled.

void	set_enabled (bool enabled) override
	Enables or disables the policy.

auto	get_policy () const -> const worker_policy &
	Gets the current worker policy configuration.

void	set_policy (const worker_policy &config)
	Updates the worker policy configuration.

auto	get_steal_policy () const -> steal_policy
	Gets the steal policy (victim selection strategy).

void	set_steal_policy (steal_policy policy)
	Sets the steal policy (victim selection strategy).

auto	get_max_steal_attempts () const -> std::size_t
	Gets the maximum steal attempts per steal cycle.

void	set_max_steal_attempts (std::size_t attempts)
	Sets the maximum steal attempts per steal cycle.

auto	get_steal_backoff () const -> std::chrono::microseconds
	Gets the steal backoff duration.

void	set_steal_backoff (std::chrono::microseconds backoff)
	Sets the steal backoff duration.

auto	get_successful_steals () const -> std::uint64_t
	Gets the total number of successful steals.

auto	get_failed_steals () const -> std::uint64_t
	Gets the total number of failed steal attempts.

void	reset_stats ()
	Resets the steal statistics.

void	record_successful_steal ()
	Records a successful steal operation.

void	record_failed_steal ()
	Records a failed steal attempt.

Public Member Functions inherited from kcenon::thread::pool_policy
virtual	~pool_policy ()=default
	Virtual destructor for proper cleanup.

Private Attributes
worker_policy	policy_

std::atomic< bool >	enabled_

std::atomic< std::uint64_t >	successful_steals_ {0}

std::atomic< std::uint64_t >	failed_steals_ {0}

Detailed Description

Pool policy that implements work-stealing behavior for load balancing.

This policy wraps the work-stealing functionality as a composable pool policy, enabling work-stealing configuration without modifying the thread_pool class.

Work-Stealing Pattern

Work-stealing enables idle workers to "steal" jobs from busy workers' local queues, improving load balancing and throughput:

Workers first check their local queue for work
If empty, they attempt to steal from other workers
Victim selection can be random, round-robin, or adaptive

Thread Safety

All methods are thread-safe and can be called from any thread.

Usage Example

worker_policy config;
config.enable_work_stealing = true;
config.victim_selection = steal_policy::adaptive;
config.max_steal_attempts = 5;
 
auto pool = std::make_shared<thread_pool>("my_pool");
auto ws_policy = std::make_unique<work_stealing_pool_policy>(config);
pool->add_policy(std::move(ws_policy));
 
pool->start();

See also: pool_policy; worker_policy

Definition at line 62 of file work_stealing_pool_policy.h.

Constructor & Destructor Documentation

◆ work_stealing_pool_policy() [1/3]

kcenon::thread::work_stealing_pool_policy::work_stealing_pool_policy ( const worker_policy & config = {} )

explicit

Constructs a work-stealing policy with the given configuration.

Parameters

config Worker policy configuration containing work-stealing settings.

Definition at line 11 of file work_stealing_pool_policy.cpp.

    : policy_(config)
    , enabled_(config.enable_work_stealing)
{
}

◆ ~work_stealing_pool_policy()

kcenon::thread::work_stealing_pool_policy::~work_stealing_pool_policy ( )

overridedefault

Destructor.

◆ work_stealing_pool_policy() [2/3]

kcenon::thread::work_stealing_pool_policy::work_stealing_pool_policy ( const work_stealing_pool_policy & )

delete

◆ work_stealing_pool_policy() [3/3]

kcenon::thread::work_stealing_pool_policy::work_stealing_pool_policy ( work_stealing_pool_policy && )

delete

Member Function Documentation

◆ get_failed_steals()

auto kcenon::thread::work_stealing_pool_policy::get_failed_steals ( ) const -> std::uint64_t

nodiscard

Gets the total number of failed steal attempts.

Returns: Number of failed steal attempts.

Definition at line 98 of file work_stealing_pool_policy.cpp.

{
    return failed_steals_.load(std::memory_order_acquire);
}

References failed_steals_.

◆ get_max_steal_attempts()

auto kcenon::thread::work_stealing_pool_policy::get_max_steal_attempts ( ) const -> std::size_t

nodiscard

Gets the maximum steal attempts per steal cycle.

Returns: Maximum steal attempts.

Definition at line 73 of file work_stealing_pool_policy.cpp.

{
    return policy_.max_steal_attempts;
}

References kcenon::thread::worker_policy::max_steal_attempts, and policy_.

◆ get_name()

auto kcenon::thread::work_stealing_pool_policy::get_name ( ) const -> std::string

nodiscardoverridevirtual

Gets the policy name.

Returns: "work_stealing_pool_policy"

Implements kcenon::thread::pool_policy.

Definition at line 36 of file work_stealing_pool_policy.cpp.

{
    return "work_stealing_pool_policy";
}

◆ get_policy()

auto kcenon::thread::work_stealing_pool_policy::get_policy ( ) const -> const worker_policy&

nodiscard

Gets the current worker policy configuration.

Returns: Const reference to the worker policy.

Definition at line 52 of file work_stealing_pool_policy.cpp.

{
    return policy_;
}

References policy_.

◆ get_steal_backoff()

auto kcenon::thread::work_stealing_pool_policy::get_steal_backoff ( ) const -> std::chrono::microseconds

nodiscard

Gets the steal backoff duration.

Returns: Backoff duration between steal attempts.

Definition at line 83 of file work_stealing_pool_policy.cpp.

{
    return policy_.steal_backoff;
}

References policy_, and kcenon::thread::worker_policy::steal_backoff.

◆ get_steal_policy()

auto kcenon::thread::work_stealing_pool_policy::get_steal_policy ( ) const -> steal_policy

nodiscard

Gets the steal policy (victim selection strategy).

Returns: Current steal policy.

Definition at line 63 of file work_stealing_pool_policy.cpp.

{
    return policy_.victim_selection;
}

References policy_, and kcenon::thread::worker_policy::victim_selection.

◆ get_successful_steals()

auto kcenon::thread::work_stealing_pool_policy::get_successful_steals ( ) const -> std::uint64_t

nodiscard

Gets the total number of successful steals.

Returns: Number of successful steal operations.

Definition at line 93 of file work_stealing_pool_policy.cpp.

{
    return successful_steals_.load(std::memory_order_acquire);
}

References successful_steals_.

◆ is_enabled()

auto kcenon::thread::work_stealing_pool_policy::is_enabled ( ) const -> bool

nodiscardoverridevirtual

Checks if the policy is enabled.

Returns: True if work-stealing is enabled.

Reimplemented from kcenon::thread::pool_policy.

Definition at line 41 of file work_stealing_pool_policy.cpp.

{
    return enabled_.load(std::memory_order_acquire);
}

References enabled_.

◆ on_enqueue()

auto kcenon::thread::work_stealing_pool_policy::on_enqueue ( job & j ) -> common::VoidResult

overridevirtual

Called before a job is enqueued.

Parameters

j	Reference to the job being enqueued.

Returns: common::ok() - work stealing does not reject jobs.

Work-stealing policy does not modify enqueue behavior. Jobs are always accepted.

Implements kcenon::thread::pool_policy.

Definition at line 17 of file work_stealing_pool_policy.cpp.

{
    (void)j;  // Job not used, work-stealing doesn't affect enqueue
    return common::ok();
}

◆ on_job_complete()

void kcenon::thread::work_stealing_pool_policy::on_job_complete	(	job &	j,
		bool	success,
		const std::exception *	error = nullptr )

overridevirtual

Called when a job completes.

Parameters

j	Reference to the completed job.
success	True if job succeeded.
error	Exception pointer if job failed.

Updates internal statistics for adaptive stealing.

Implements kcenon::thread::pool_policy.

Definition at line 28 of file work_stealing_pool_policy.cpp.

{
    (void)j;      // Job not used for work-stealing statistics
    (void)success;
    (void)error;
    // Statistics are tracked through record_successful_steal/record_failed_steal
}

References kcenon::thread::success.

◆ on_job_start()

void kcenon::thread::work_stealing_pool_policy::on_job_start ( job & j )

overridevirtual

Called when job starts executing.

Parameters

j	Reference to the job.

Can be used to track job execution for steal decisions.

Implements kcenon::thread::pool_policy.

Definition at line 23 of file work_stealing_pool_policy.cpp.

{
    (void)j;  // Currently no action needed on job start
}

◆ operator=() [1/2]

work_stealing_pool_policy & kcenon::thread::work_stealing_pool_policy::operator= ( const work_stealing_pool_policy & )

delete

◆ operator=() [2/2]

work_stealing_pool_policy & kcenon::thread::work_stealing_pool_policy::operator= ( work_stealing_pool_policy && )

delete

◆ record_failed_steal()

void kcenon::thread::work_stealing_pool_policy::record_failed_steal ( )

Records a failed steal attempt.

Call this from the thread_pool when a steal fails.

Definition at line 114 of file work_stealing_pool_policy.cpp.

{
    failed_steals_.fetch_add(1, std::memory_order_relaxed);
}

References failed_steals_.

◆ record_successful_steal()

void kcenon::thread::work_stealing_pool_policy::record_successful_steal ( )

Records a successful steal operation.

Call this from the thread_pool when a steal succeeds.

Definition at line 109 of file work_stealing_pool_policy.cpp.

{
    successful_steals_.fetch_add(1, std::memory_order_relaxed);
}

References successful_steals_.

◆ reset_stats()

void kcenon::thread::work_stealing_pool_policy::reset_stats ( )

Resets the steal statistics.

Definition at line 103 of file work_stealing_pool_policy.cpp.

{
    successful_steals_.store(0, std::memory_order_release);
    failed_steals_.store(0, std::memory_order_release);
}

References failed_steals_, and successful_steals_.

◆ set_enabled()

void kcenon::thread::work_stealing_pool_policy::set_enabled ( bool enabled )

overridevirtual

Enables or disables the policy.

Parameters

enabled Whether to enable work-stealing.

Reimplemented from kcenon::thread::pool_policy.

Definition at line 46 of file work_stealing_pool_policy.cpp.

{
    enabled_.store(enabled, std::memory_order_release);
    policy_.enable_work_stealing = enabled;
}

References kcenon::thread::worker_policy::enable_work_stealing, enabled_, and policy_.

◆ set_max_steal_attempts()

void kcenon::thread::work_stealing_pool_policy::set_max_steal_attempts ( std::size_t attempts )

Sets the maximum steal attempts per steal cycle.

Parameters

attempts New maximum steal attempts.

Definition at line 78 of file work_stealing_pool_policy.cpp.

{
    policy_.max_steal_attempts = attempts;
}

References kcenon::thread::worker_policy::max_steal_attempts, and policy_.

◆ set_policy()

void kcenon::thread::work_stealing_pool_policy::set_policy ( const worker_policy & config )

Updates the worker policy configuration.

Parameters

config New worker policy configuration.

Note: Changes take effect for subsequent operations.

Definition at line 57 of file work_stealing_pool_policy.cpp.

{
    policy_ = config;
    enabled_.store(config.enable_work_stealing, std::memory_order_release);
}

References kcenon::thread::worker_policy::enable_work_stealing, enabled_, and policy_.

◆ set_steal_backoff()

void kcenon::thread::work_stealing_pool_policy::set_steal_backoff ( std::chrono::microseconds backoff )

Sets the steal backoff duration.

Parameters

backoff New backoff duration.

Definition at line 88 of file work_stealing_pool_policy.cpp.

{
    policy_.steal_backoff = backoff;
}

References policy_, and kcenon::thread::worker_policy::steal_backoff.

◆ set_steal_policy()

void kcenon::thread::work_stealing_pool_policy::set_steal_policy ( steal_policy policy )

Sets the steal policy (victim selection strategy).

Parameters

policy New steal policy.

Definition at line 68 of file work_stealing_pool_policy.cpp.

{
    policy_.victim_selection = policy;
}

References policy_, and kcenon::thread::worker_policy::victim_selection.

Member Data Documentation

◆ enabled_

std::atomic<bool> kcenon::thread::work_stealing_pool_policy::enabled_

private

Definition at line 221 of file work_stealing_pool_policy.h.

Referenced by is_enabled(), set_enabled(), and set_policy().

◆ failed_steals_

std::atomic<std::uint64_t> kcenon::thread::work_stealing_pool_policy::failed_steals_ {0}

private

Definition at line 223 of file work_stealing_pool_policy.h.

223{0};

Referenced by get_failed_steals(), record_failed_steal(), and reset_stats().

◆ policy_

worker_policy kcenon::thread::work_stealing_pool_policy::policy_

private

Definition at line 220 of file work_stealing_pool_policy.h.

Referenced by get_max_steal_attempts(), get_policy(), get_steal_backoff(), get_steal_policy(), set_enabled(), set_max_steal_attempts(), set_policy(), set_steal_backoff(), and set_steal_policy().

◆ successful_steals_

std::atomic<std::uint64_t> kcenon::thread::work_stealing_pool_policy::successful_steals_ {0}

private

Definition at line 222 of file work_stealing_pool_policy.h.

222{0};

Referenced by get_successful_steals(), record_successful_steal(), and reset_stats().

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

include/kcenon/thread/pool_policies/work_stealing_pool_policy.h
src/pool_policies/work_stealing_pool_policy.cpp

Public Member Functions

Private Attributes

Detailed Description

Work-Stealing Pattern

Thread Safety

Usage Example

Constructor & Destructor Documentation

◆ work_stealing_pool_policy() [1/3]

◆ ~work_stealing_pool_policy()

◆ work_stealing_pool_policy() [2/3]

◆ work_stealing_pool_policy() [3/3]

Member Function Documentation

◆ get_failed_steals()

◆ get_max_steal_attempts()

◆ get_name()

◆ get_policy()

◆ get_steal_backoff()

◆ get_steal_policy()

◆ get_successful_steals()

◆ is_enabled()

◆ on_enqueue()

◆ on_job_complete()

◆ on_job_start()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ record_failed_steal()

◆ record_successful_steal()

◆ reset_stats()

◆ set_enabled()

◆ set_max_steal_attempts()

◆ set_policy()

◆ set_steal_backoff()

◆ set_steal_policy()

Member Data Documentation

◆ enabled_

◆ failed_steals_

◆ policy_

◆ successful_steals_