Thread-safe circuit breaker for fault tolerance. More...

#include <circuit_breaker.h>

Inheritance diagram for kcenon::common::resilience::circuit_breaker:

Collaboration diagram for kcenon::common::resilience::circuit_breaker:

Classes
class	guard
	RAII guard for automatic success/failure recording. More...

Public Types
using	clock_type = std::chrono::steady_clock

using	time_point = clock_type::time_point

Public Member Functions
	circuit_breaker (circuit_breaker_config config={})
	Construct circuit breaker with specified configuration.

auto	allow_request () -> bool
	Check if request should be allowed through the circuit.

auto	record_success () -> void
	Record a successful operation. May trigger state transition from HALF_OPEN to CLOSED.

auto	record_failure (const std::exception *e=nullptr) -> void
	Record a failed operation. May trigger state transition to OPEN or back to OPEN from HALF_OPEN.

auto	get_state () const -> circuit_state
	Get current circuit state.

auto	make_guard () -> guard
	Create RAII guard for automatic recording.

auto	get_stats () const -> std::unordered_map< std::string, interfaces::stats_value > override
	Get current statistics as key-value pairs.

auto	to_json () const -> std::string override
	Get statistics as JSON string.

auto	name () const -> std::string_view override
	Get component name for identification.

Public Member Functions inherited from kcenon::common::interfaces::IStats
virtual	~IStats ()=default

virtual auto	get_snapshot () const -> stats_snapshot
	Get a complete statistics snapshot with metadata.

Private Member Functions
auto	should_attempt_reset () const -> bool
	Check if circuit should attempt reset to HALF_OPEN. Must be called with mutex locked.

auto	transition_to_closed () -> void
	Transition to CLOSED state. Must be called with mutex locked.

auto	transition_to_open () -> void
	Transition to OPEN state. Must be called with mutex locked.

auto	transition_to_half_open () -> void
	Transition to HALF_OPEN state. Must be called with mutex locked.

Private Attributes
circuit_breaker_config	config_

std::atomic< circuit_state >	state_

failure_window	failure_window_

std::size_t	consecutive_successes_

std::size_t	half_open_requests_

time_point	last_state_change_

std::mutex	mutex_

Detailed Description

Thread-safe circuit breaker for fault tolerance.

Usage Example:

circuit_breaker_config config{
    .failure_threshold = 5,
    .timeout = std::chrono::seconds(30)
};
circuit_breaker breaker(config);
 
// Check before making request
if (!breaker.allow_request()) {
    // Circuit is open, handle gracefully
    return error("Service unavailable");
}
 
// Use RAII guard for automatic recording
{
    auto guard = breaker.make_guard();
    // Make risky operation
    auto result = risky_operation();
    guard.record_success(); // Mark as success if no exception
} // Automatically records failure if exception thrown

Thread Safety:

All public methods are thread-safe.
Safe for concurrent access from multiple threads.
State transitions are protected by internal synchronization.

Examples: circuit_breaker_example.cpp.

Definition at line 68 of file circuit_breaker.h.

Member Typedef Documentation

◆ clock_type

using kcenon::common::resilience::circuit_breaker::clock_type = std::chrono::steady_clock

Definition at line 70 of file circuit_breaker.h.

◆ time_point

using kcenon::common::resilience::circuit_breaker::time_point = clock_type::time_point

Definition at line 71 of file circuit_breaker.h.

Constructor & Destructor Documentation

◆ circuit_breaker()

kcenon::common::resilience::circuit_breaker::circuit_breaker ( circuit_breaker_config config = {} )

inlineexplicit

Construct circuit breaker with specified configuration.

Parameters

config Configuration parameters (thresholds, timeouts)

Definition at line 77 of file circuit_breaker.h.

                                                             {})
        : config_(std::move(config))
        , state_(circuit_state::CLOSED)
        , failure_window_(config_.failure_window)
        , consecutive_successes_(0)
        , half_open_requests_(0)
        , last_state_change_(clock_type::now())
    {
    }

Member Function Documentation

◆ allow_request()

auto kcenon::common::resilience::circuit_breaker::allow_request ( ) -> bool

inlinenodiscard

Check if request should be allowed through the circuit.

Returns: true if request is allowed, false if circuit is open

Definition at line 91 of file circuit_breaker.h.

    {
        std::lock_guard<std::mutex> lock(mutex_);
 
        switch (state_) {
        case circuit_state::CLOSED:
            return true;
 
        case circuit_state::OPEN:
            // Check if timeout has elapsed to attempt recovery
            if (should_attempt_reset()) {
                transition_to_half_open();
                // First request in HALF_OPEN counts toward the limit
                ++half_open_requests_;
                return true;
            }
            return false;
 
        case circuit_state::HALF_OPEN:
            // Allow limited requests for testing
            if (half_open_requests_ < config_.half_open_max_requests) {
                ++half_open_requests_;
                return true;
            }
            return false;
        }
 
        return false; // Unreachable, but satisfies compiler
    }

References kcenon::common::resilience::CLOSED, config_, kcenon::common::resilience::HALF_OPEN, kcenon::common::resilience::circuit_breaker_config::half_open_max_requests, half_open_requests_, mutex_, kcenon::common::resilience::OPEN, should_attempt_reset(), state_, and transition_to_half_open().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_state()

auto kcenon::common::resilience::circuit_breaker::get_state ( ) const -> circuit_state

inlinenodiscard

Get current circuit state.

Returns: Current state (CLOSED, OPEN, or HALF_OPEN)

Definition at line 165 of file circuit_breaker.h.

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

References state_.

Referenced by main().

Here is the caller graph for this function:

◆ get_stats()

auto kcenon::common::resilience::circuit_breaker::get_stats ( ) const -> std::unordered_map<std::string, interfaces::stats_value>

inlinenodiscardoverridevirtual

Get current statistics as key-value pairs.

Returns: Map of metric names to values (state, counts, rates)

Implements kcenon::common::interfaces::IStats.

Definition at line 224 of file circuit_breaker.h.

    {
        std::lock_guard<std::mutex> lock(mutex_);
 
        const auto current_state = state_.load(std::memory_order_acquire);
        const auto failure_count = failure_window_.get_failure_count();
 
        return {
            {"current_state", to_string(current_state)},
            {"failure_count", static_cast<std::int64_t>(failure_count)},
            {"consecutive_successes", static_cast<std::int64_t>(consecutive_successes_)},
            {"half_open_requests", static_cast<std::int64_t>(half_open_requests_)},
            {"failure_threshold", static_cast<std::int64_t>(config_.failure_threshold)},
            {"is_open", current_state == circuit_state::OPEN}
        };
    }

References config_, consecutive_successes_, kcenon::common::resilience::circuit_breaker_config::failure_threshold, failure_window_, kcenon::common::resilience::failure_window::get_failure_count(), half_open_requests_, mutex_, kcenon::common::resilience::OPEN, state_, and kcenon::common::resilience::to_string().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ make_guard()

auto kcenon::common::resilience::circuit_breaker::make_guard ( ) -> guard

inlinenodiscard

Create RAII guard for automatic recording.

Returns: Guard object that records failure unless success is called

Definition at line 216 of file circuit_breaker.h.

216{ return guard(*this); }

Referenced by main().

Here is the caller graph for this function:

◆ name()

auto kcenon::common::resilience::circuit_breaker::name ( ) const -> std::string_view

inlinenodiscardoverridevirtual

Get component name for identification.

Returns: Component name "circuit_breaker"

Implements kcenon::common::interfaces::IStats.

Definition at line 255 of file circuit_breaker.h.

    {
        return "circuit_breaker";
    }

◆ record_failure()

auto kcenon::common::resilience::circuit_breaker::record_failure ( const std::exception * e = nullptr ) -> void

inline

Record a failed operation. May trigger state transition to OPEN or back to OPEN from HALF_OPEN.

Parameters

e	Optional exception pointer for logging/metrics

Definition at line 142 of file circuit_breaker.h.

    {
        (void)e; // Reserved for future metrics/logging integration
 
        std::lock_guard<std::mutex> lock(mutex_);
 
        failure_window_.record_failure();
 
        if (state_ == circuit_state::HALF_OPEN) {
            // Any failure in half-open immediately reopens circuit
            transition_to_open();
        } else if (state_ == circuit_state::CLOSED) {
            // Check if failure threshold exceeded
            if (failure_window_.get_failure_count() >= config_.failure_threshold) {
                transition_to_open();
            }
        }
    }

References kcenon::common::resilience::CLOSED, config_, kcenon::common::resilience::circuit_breaker_config::failure_threshold, failure_window_, kcenon::common::resilience::failure_window::get_failure_count(), kcenon::common::resilience::HALF_OPEN, mutex_, kcenon::common::resilience::failure_window::record_failure(), state_, and transition_to_open().

Referenced by kcenon::common::resilience::circuit_breaker::guard::~guard().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ record_success()

auto kcenon::common::resilience::circuit_breaker::record_success ( ) -> void

inline

Record a successful operation. May trigger state transition from HALF_OPEN to CLOSED.

Definition at line 125 of file circuit_breaker.h.

    {
        std::lock_guard<std::mutex> lock(mutex_);
 
        if (state_ == circuit_state::HALF_OPEN) {
            ++consecutive_successes_;
            if (consecutive_successes_ >= config_.success_threshold) {
                transition_to_closed();
            }
        }
    }

References config_, consecutive_successes_, kcenon::common::resilience::HALF_OPEN, mutex_, state_, kcenon::common::resilience::circuit_breaker_config::success_threshold, and transition_to_closed().

Referenced by kcenon::common::resilience::circuit_breaker::guard::record_success().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ should_attempt_reset()

auto kcenon::common::resilience::circuit_breaker::should_attempt_reset ( ) const -> bool

inlinenodiscardprivate

Check if circuit should attempt reset to HALF_OPEN. Must be called with mutex locked.

Definition at line 265 of file circuit_breaker.h.

    {
        const auto now = clock_type::now();
        const auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
            now - last_state_change_);
        return elapsed >= config_.timeout;
    }

References config_, last_state_change_, and kcenon::common::resilience::circuit_breaker_config::timeout.

Referenced by allow_request().

Here is the caller graph for this function:

◆ to_json()

auto kcenon::common::resilience::circuit_breaker::to_json ( ) const -> std::string

inlinenodiscardoverridevirtual

Get statistics as JSON string.

Returns: JSON representation of current statistics

Implements kcenon::common::interfaces::IStats.

Definition at line 245 of file circuit_breaker.h.

    {
        const auto snapshot = get_snapshot();
        return snapshot.to_json();
    }

References kcenon::common::interfaces::IStats::get_snapshot().

Here is the call graph for this function:

◆ transition_to_closed()

auto kcenon::common::resilience::circuit_breaker::transition_to_closed ( ) -> void

inlineprivate

Transition to CLOSED state. Must be called with mutex locked.

Definition at line 277 of file circuit_breaker.h.

    {
        state_.store(circuit_state::CLOSED, std::memory_order_release);
        failure_window_.reset();
        consecutive_successes_ = 0;
        half_open_requests_ = 0;
        last_state_change_ = clock_type::now();
    }

References kcenon::common::resilience::CLOSED, consecutive_successes_, failure_window_, half_open_requests_, last_state_change_, kcenon::common::resilience::failure_window::reset(), and state_.

Referenced by record_success().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ transition_to_half_open()

auto kcenon::common::resilience::circuit_breaker::transition_to_half_open ( ) -> void

inlineprivate

Transition to HALF_OPEN state. Must be called with mutex locked.

Definition at line 302 of file circuit_breaker.h.

    {
        state_.store(circuit_state::HALF_OPEN, std::memory_order_release);
        consecutive_successes_ = 0;
        half_open_requests_ = 0;
        last_state_change_ = clock_type::now();
    }

References consecutive_successes_, kcenon::common::resilience::HALF_OPEN, half_open_requests_, last_state_change_, and state_.

Referenced by allow_request().

Here is the caller graph for this function:

◆ transition_to_open()

auto kcenon::common::resilience::circuit_breaker::transition_to_open ( ) -> void

inlineprivate

Transition to OPEN state. Must be called with mutex locked.

Definition at line 290 of file circuit_breaker.h.

    {
        state_.store(circuit_state::OPEN, std::memory_order_release);
        consecutive_successes_ = 0;
        half_open_requests_ = 0;
        last_state_change_ = clock_type::now();
    }

References consecutive_successes_, half_open_requests_, last_state_change_, kcenon::common::resilience::OPEN, and state_.

Referenced by record_failure().

Here is the caller graph for this function:

Member Data Documentation

◆ config_

circuit_breaker_config kcenon::common::resilience::circuit_breaker::config_

private

Definition at line 310 of file circuit_breaker.h.

Referenced by allow_request(), get_stats(), record_failure(), record_success(), and should_attempt_reset().

◆ consecutive_successes_

std::size_t kcenon::common::resilience::circuit_breaker::consecutive_successes_

private

Definition at line 313 of file circuit_breaker.h.

Referenced by get_stats(), record_success(), transition_to_closed(), transition_to_half_open(), and transition_to_open().

◆ failure_window_

failure_window kcenon::common::resilience::circuit_breaker::failure_window_

private

Definition at line 312 of file circuit_breaker.h.

Referenced by get_stats(), record_failure(), and transition_to_closed().

◆ half_open_requests_

std::size_t kcenon::common::resilience::circuit_breaker::half_open_requests_

private

Definition at line 314 of file circuit_breaker.h.

Referenced by allow_request(), get_stats(), transition_to_closed(), transition_to_half_open(), and transition_to_open().

◆ last_state_change_

time_point kcenon::common::resilience::circuit_breaker::last_state_change_

private

Definition at line 315 of file circuit_breaker.h.

Referenced by should_attempt_reset(), transition_to_closed(), transition_to_half_open(), and transition_to_open().

◆ mutex_

std::mutex kcenon::common::resilience::circuit_breaker::mutex_

mutableprivate

Definition at line 316 of file circuit_breaker.h.

Referenced by allow_request(), get_stats(), record_failure(), and record_success().

◆ state_

std::atomic<circuit_state> kcenon::common::resilience::circuit_breaker::state_

private

Definition at line 311 of file circuit_breaker.h.

Referenced by allow_request(), get_state(), get_stats(), record_failure(), record_success(), transition_to_closed(), transition_to_half_open(), and transition_to_open().

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

include/kcenon/common/resilience/circuit_breaker.h

Classes

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ clock_type

◆ time_point

Constructor & Destructor Documentation

◆ circuit_breaker()

Member Function Documentation

◆ allow_request()

◆ get_state()

◆ get_stats()

◆ make_guard()

◆ name()

◆ record_failure()

◆ record_success()

◆ should_attempt_reset()

◆ to_json()

◆ transition_to_closed()

◆ transition_to_half_open()

◆ transition_to_open()

Member Data Documentation

◆ config_

◆ consecutive_successes_

◆ failure_window_

◆ half_open_requests_

◆ last_state_change_

◆ mutex_

◆ state_