kcenon::thread::backoff_calculator Class Reference

Calculates backoff delays for work-stealing operations. More...

#include <steal_backoff_strategy.h>

Collaboration diagram for kcenon::thread::backoff_calculator:

Public Member Functions
	backoff_calculator (steal_backoff_config config={})
	Construct a backoff calculator with given configuration.
auto	calculate (std::size_t attempt) -> std::chrono::microseconds
	Calculate backoff delay for a given attempt number.
auto	get_config () const -> const steal_backoff_config &
	Get the current configuration.
void	set_config (steal_backoff_config config)
	Update the configuration.

Private Member Functions
auto	calculate_base_delay (std::size_t attempt) const -> std::chrono::microseconds
	Calculate base delay without jitter or capping.
auto	apply_jitter (std::chrono::microseconds delay) -> std::chrono::microseconds
	Apply random jitter to a delay.
auto	cap_delay (std::chrono::microseconds delay) const -> std::chrono::microseconds
	Cap delay at maximum.

Private Attributes
steal_backoff_config	config_
std::mt19937_64	rng_

Detailed Description

Calculates backoff delays for work-stealing operations.

This class provides thread-safe backoff delay calculation using various strategies. It is designed to be used by workers when steal attempts fail.

Thread Safety

Each worker should have its own backoff_calculator instance to avoid contention on the random number generator. All methods are thread-safe when used with separate instances.

Usage Example

steal_backoff_config config;
config.strategy = steal_backoff_strategy::exponential;
config.initial_backoff = std::chrono::microseconds{50};
config.max_backoff = std::chrono::microseconds{1000};
 
backoff_calculator calculator(config);
 
// On steal failure
std::size_t attempt = 0;
while (!steal_successful && attempt < max_attempts) {
    auto delay = calculator.calculate(attempt);
    std::this_thread::sleep_for(delay);
    ++attempt;
}

Definition at line 90 of file steal_backoff_strategy.h.

Constructor & Destructor Documentation

backoff_calculator()

kcenon::thread::backoff_calculator::backoff_calculator ( steal_backoff_config config = {} )

inlineexplicit

Construct a backoff calculator with given configuration.

Parameters

config

Backoff configuration

Definition at line 97 of file steal_backoff_strategy.h.

                                                              {})
        : config_(config)
        , rng_(std::random_device{}())
    {
    }

Member Function Documentation

apply_jitter()

auto kcenon::thread::backoff_calculator::apply_jitter ( std::chrono::microseconds delay ) -> std::chrono::microseconds

inlinenodiscardprivate

Apply random jitter to a delay.

Definition at line 186 of file steal_backoff_strategy.h.

    {
        using rep = std::chrono::microseconds::rep;
        rep base = delay.count();
        rep jitter_range =
            static_cast<rep>(static_cast<double>(base) * config_.jitter_factor);
 
        if (jitter_range <= 0)
        {
            return delay;
        }
 
        std::uniform_int_distribution<rep> dist(-jitter_range, jitter_range);
        rep jittered = base + dist(rng_);
 
        // Ensure we don't go negative
        return std::chrono::microseconds{std::max(rep{1}, jittered)};
    }

References config_, kcenon::thread::delay, kcenon::thread::steal_backoff_config::jitter_factor, and rng_.

Referenced by calculate().

Here is the caller graph for this function:

calculate()

auto kcenon::thread::backoff_calculator::calculate ( std::size_t attempt ) -> std::chrono::microseconds

inlinenodiscard

Calculate backoff delay for a given attempt number.

Parameters

attempt

The attempt number (0-indexed)

Returns

Calculated backoff delay

The delay is calculated based on the configured strategy and capped at max_backoff.

Definition at line 111 of file steal_backoff_strategy.h.

    {
        auto delay = calculate_base_delay(attempt);
 
        if (config_.strategy == steal_backoff_strategy::adaptive_jitter)
        {
            delay = apply_jitter(delay);
        }
 
        return cap_delay(delay);
    }

References kcenon::thread::adaptive_jitter, apply_jitter(), calculate_base_delay(), cap_delay(), config_, kcenon::thread::delay, and kcenon::thread::steal_backoff_config::strategy.

Here is the call graph for this function:

calculate_base_delay()

auto kcenon::thread::backoff_calculator::calculate_base_delay ( std::size_t attempt ) const -> std::chrono::microseconds

inlinenodiscardprivate

Calculate base delay without jitter or capping.

Definition at line 145 of file steal_backoff_strategy.h.

    {
        auto initial = static_cast<double>(config_.initial_backoff.count());
        auto max_count = static_cast<double>(config_.max_backoff.count());
 
        switch (config_.strategy)
        {
        case steal_backoff_strategy::fixed:
            return config_.initial_backoff;
 
        case steal_backoff_strategy::linear:
            return std::chrono::microseconds{
                static_cast<std::int64_t>(initial * static_cast<double>(attempt + 1))};
 
        case steal_backoff_strategy::exponential:
        case steal_backoff_strategy::adaptive_jitter:
        {
            // Calculate multiplier^attempt with overflow protection
            double factor = 1.0;
            for (std::size_t i = 0; i < attempt; ++i)
            {
                factor *= config_.multiplier;
                // Early exit if we've exceeded max to avoid unnecessary computation
                if (factor * initial > max_count)
                {
                    return config_.max_backoff;
                }
            }
            return std::chrono::microseconds{
                static_cast<std::int64_t>(initial * factor)};
        }
 
        default:
            return config_.initial_backoff;
        }
    }

References kcenon::thread::adaptive_jitter, config_, kcenon::thread::exponential, kcenon::thread::fixed, kcenon::thread::steal_backoff_config::initial_backoff, kcenon::thread::linear, kcenon::thread::steal_backoff_config::max_backoff, kcenon::thread::steal_backoff_config::multiplier, and kcenon::thread::steal_backoff_config::strategy.

Referenced by calculate().

Here is the caller graph for this function:

cap_delay()

auto kcenon::thread::backoff_calculator::cap_delay ( std::chrono::microseconds delay ) const -> std::chrono::microseconds

inlinenodiscardprivate

Cap delay at maximum.

Definition at line 209 of file steal_backoff_strategy.h.

    {
        return std::min(delay, config_.max_backoff);
    }

References config_, kcenon::thread::delay, and kcenon::thread::steal_backoff_config::max_backoff.

Referenced by calculate().

Here is the caller graph for this function:

get_config()

auto kcenon::thread::backoff_calculator::get_config ( ) const -> const steal_backoff_config&

inlinenodiscard

Get the current configuration.

Returns

Reference to the backoff configuration

Definition at line 127 of file steal_backoff_strategy.h.

    {
        return config_;
    }

References config_.

set_config()

void kcenon::thread::backoff_calculator::set_config ( steal_backoff_config config )

inline

Update the configuration.

Parameters

config

New configuration to use

Definition at line 136 of file steal_backoff_strategy.h.

    {
        config_ = config;
    }

References config_.

Member Data Documentation

config_

steal_backoff_config kcenon::thread::backoff_calculator::config_

private

Definition at line 215 of file steal_backoff_strategy.h.

Referenced by apply_jitter(), calculate(), calculate_base_delay(), cap_delay(), get_config(), and set_config().

rng_

std::mt19937_64 kcenon::thread::backoff_calculator::rng_

private

Definition at line 216 of file steal_backoff_strategy.h.

Referenced by apply_jitter().

---

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

• include/kcenon/thread/stealing/steal_backoff_strategy.h