Configuration for backpressure mechanisms. More...

#include <backpressure_config.h>

Collaboration diagram for kcenon::thread::backpressure_config:

Public Member Functions
auto	is_valid () const -> bool
	Validates the configuration.

Public Attributes
backpressure_policy	policy = backpressure_policy::block
	The backpressure policy to use.

double	high_watermark = 0.8
	High watermark threshold (percentage of max_size).

double	low_watermark = 0.5
	Low watermark threshold (percentage of max_size).

std::chrono::milliseconds	block_timeout {5000}
	Maximum time to block when using block policy.

bool	enable_rate_limiting = false
	Enable token bucket rate limiting.

std::size_t	rate_limit_tokens_per_second = 10000
	Token refill rate (tokens added per second).

std::size_t	rate_limit_burst_size = 1000
	Maximum tokens that can accumulate (burst capacity).

std::function< void(std::size_t queue_depth, double pressure_ratio)>	pressure_callback
	Callback for pressure events.

std::function< backpressure_decision(std::unique_ptr< job > &)>	decision_callback
	Custom decision callback for callback policy.

std::chrono::milliseconds	adaptive_sample_interval {100}
	Sampling interval for adaptive mode.

double	adaptive_target_latency_ms = 10.0
	Target latency for adaptive mode (milliseconds).

Detailed Description

Configuration for backpressure mechanisms.

This structure contains all configurable parameters for the backpressure system, including policy selection, watermarks, rate limiting, and callbacks.

Watermarks

Watermarks define pressure thresholds as percentages of max_size:

0%                    50%              80%           100%
|------ none ---------|---- low -------|--- high ----|critical|
                   low_watermark    high_watermark  max_size

Rate Limiting

When enabled, the token bucket algorithm limits the rate of job acceptance regardless of queue capacity.

Adaptive Mode

In adaptive mode, the system monitors latency and automatically adjusts acceptance rate to maintain target latency.

Usage Example

backpressure_config config;
config.policy = backpressure_policy::adaptive;
config.high_watermark = 0.75;
config.enable_rate_limiting = true;
config.rate_limit_tokens_per_second = 5000;
config.pressure_callback = [](std::size_t depth, double ratio) {
    LOG_WARN("Queue pressure: {:.1f}%", ratio * 100);
};

Definition at line 166 of file backpressure_config.h.

Member Function Documentation

◆ is_valid()

auto kcenon::thread::backpressure_config::is_valid ( ) const -> bool

inlinenodiscard

Validates the configuration.

Returns: true if configuration is valid, false otherwise.

Checks:

Watermarks are in valid range (0.0 to 1.0)
low_watermark < high_watermark
Required callbacks are set for callback policy

Definition at line 300 of file backpressure_config.h.

        {
            // Watermark validation
            if (low_watermark < 0.0 || low_watermark > 1.0)
            {
                return false;
            }
            if (high_watermark < 0.0 || high_watermark > 1.0)
            {
                return false;
            }
            if (low_watermark >= high_watermark)
            {
                return false;
            }
 
            // Callback policy requires decision_callback
            if (policy == backpressure_policy::callback && !decision_callback)
            {
                return false;
            }
 
            // Rate limiting validation
            if (enable_rate_limiting)
            {
                if (rate_limit_tokens_per_second == 0)
                {
                    return false;
                }
                if (rate_limit_burst_size == 0)
                {
                    return false;
                }
            }
 
            return true;
        }

References kcenon::thread::callback, decision_callback, enable_rate_limiting, high_watermark, low_watermark, policy, rate_limit_burst_size, and rate_limit_tokens_per_second.

Referenced by kcenon::thread::thread_system_config::is_valid().

Here is the caller graph for this function:

Member Data Documentation

◆ adaptive_sample_interval

std::chrono::milliseconds kcenon::thread::backpressure_config::adaptive_sample_interval {100}

Sampling interval for adaptive mode.

How frequently the adaptive controller samples queue state to adjust its parameters.

Definition at line 281 of file backpressure_config.h.

281{100};

◆ adaptive_target_latency_ms

double kcenon::thread::backpressure_config::adaptive_target_latency_ms = 10.0

Target latency for adaptive mode (milliseconds).

The adaptive controller tries to maintain average queue wait time at or below this target by adjusting acceptance rate.

Definition at line 289 of file backpressure_config.h.

◆ block_timeout

std::chrono::milliseconds kcenon::thread::backpressure_config::block_timeout {5000}

Maximum time to block when using block policy.

If the timeout expires before space becomes available, the enqueue operation returns an error.

Definition at line 215 of file backpressure_config.h.

215{5000};

◆ decision_callback

std::function<backpressure_decision(std::unique_ptr<job>&)> kcenon::thread::backpressure_config::decision_callback

Custom decision callback for callback policy.

Called when policy is backpressure_policy::callback. Receives reference to the job being enqueued. Returns backpressure_decision indicating how to proceed.

Note: The callback should be fast as it's called in the enqueue path.

Definition at line 269 of file backpressure_config.h.

Referenced by is_valid().

◆ enable_rate_limiting

bool kcenon::thread::backpressure_config::enable_rate_limiting = false

Enable token bucket rate limiting.

When enabled, job acceptance is limited by a token bucket regardless of queue capacity.

Definition at line 227 of file backpressure_config.h.

Referenced by kcenon::thread::backpressure_job_queue::backpressure_job_queue(), kcenon::thread::backpressure_job_queue::get_available_tokens(), kcenon::thread::backpressure_job_queue::is_rate_limited(), and is_valid().

◆ high_watermark

double kcenon::thread::backpressure_config::high_watermark = 0.8

High watermark threshold (percentage of max_size).

When queue depth exceeds this threshold, pressure is considered "high". Range: 0.0 to 1.0 (e.g., 0.8 = 80% of capacity)

Definition at line 194 of file backpressure_config.h.

Referenced by is_valid(), and kcenon::thread::config_builder::with_watermarks().

◆ low_watermark

double kcenon::thread::backpressure_config::low_watermark = 0.5

Low watermark threshold (percentage of max_size).

When queue depth falls below this threshold, pressure returns to "none". Used for hysteresis to prevent oscillation. Range: 0.0 to 1.0 (e.g., 0.5 = 50% of capacity)

Definition at line 203 of file backpressure_config.h.

Referenced by is_valid(), and kcenon::thread::config_builder::with_watermarks().

◆ policy

backpressure_policy kcenon::thread::backpressure_config::policy = backpressure_policy::block

The backpressure policy to use.

Determines how the queue handles overflow conditions:

block: Wait with timeout
drop_oldest: Remove oldest job to make room
drop_newest: Reject new job
callback: Call user callback for decision
adaptive: Auto-adjust based on conditions

Examples: config_example.cpp.

Definition at line 182 of file backpressure_config.h.

Referenced by kcenon::thread::config_builder::enable_backpressure(), is_valid(), kcenon::thread::backpressure_job_queue::to_string(), and kcenon::thread::config_builder::with_backpressure_policy().

◆ pressure_callback

std::function<void(std::size_t queue_depth, double pressure_ratio)> kcenon::thread::backpressure_config::pressure_callback

Callback for pressure events.

Called when pressure level changes. Receives:

queue_depth: Current number of jobs in queue
pressure_ratio: Current depth as ratio of max_size (0.0 to 1.0+)

Useful for logging, alerting, or triggering external actions.

Definition at line 258 of file backpressure_config.h.

◆ rate_limit_burst_size

std::size_t kcenon::thread::backpressure_config::rate_limit_burst_size = 1000

Maximum tokens that can accumulate (burst capacity).

Allows short bursts above the sustained rate. Only effective when enable_rate_limiting is true.

Definition at line 243 of file backpressure_config.h.

Referenced by kcenon::thread::backpressure_job_queue::is_rate_limited(), and is_valid().

◆ rate_limit_tokens_per_second

std::size_t kcenon::thread::backpressure_config::rate_limit_tokens_per_second = 10000

Token refill rate (tokens added per second).

Determines the sustained throughput limit. Only effective when enable_rate_limiting is true.

Definition at line 235 of file backpressure_config.h.