Holds information about why a cancellation occurred. More...

#include <cancellation_reason.h>

Collaboration diagram for kcenon::thread::cancellation_reason:

Public Types
enum class	type { none , user_requested , timeout , deadline , parent_cancelled , pool_shutdown , error }
	The type of cancellation that occurred. More...

Public Member Functions
auto	to_string () const -> std::string
	Converts the cancellation reason to a human-readable string.

Static Public Member Functions
static auto	type_to_string (type t) -> std::string
	Converts the reason type enum to a string.

Public Attributes
type	reason_type = type::none
	The type of cancellation that occurred.

std::string	message
	Human-readable message describing the cancellation.

std::chrono::steady_clock::time_point	cancel_time
	Time point when the cancellation occurred.

std::optional< std::exception_ptr >	exception
	Optional exception that triggered the cancellation.

Detailed Description

Holds information about why a cancellation occurred.

When a cancellation token is cancelled, the reason provides details about what triggered the cancellation, when it occurred, and optionally any exception that caused it.

Usage Example

auto token = enhanced_cancellation_token::create_with_timeout(
    std::chrono::seconds{30});
 
// ... later, when cancelled ...
if (token.is_cancelled()) {
    auto reason = token.get_reason();
    if (reason) {
        std::cout << "Cancelled: " << reason->to_string() << std::endl;
    }
}

Definition at line 50 of file cancellation_reason.h.

Member Enumeration Documentation

◆ type

enum class kcenon::thread::cancellation_reason::type

strong

The type of cancellation that occurred.

Enumerator
none	No cancellation (default state)
user_requested	Explicit cancel() call by user.
timeout	Timeout duration expired.
deadline	Deadline time point reached.
parent_cancelled	Parent token was cancelled.
pool_shutdown	Thread pool is shutting down.
error	Cancellation triggered by an error.

Definition at line 56 of file cancellation_reason.h.

        {
            none,              
            user_requested,    
            timeout,           
            deadline,          
            parent_cancelled,  
            pool_shutdown,     
            error              
        };

Member Function Documentation

◆ to_string()

auto kcenon::thread::cancellation_reason::to_string ( ) const -> std::string

inlinenodiscard

Converts the cancellation reason to a human-readable string.

Returns: A string describing the cancellation reason.

Definition at line 83 of file cancellation_reason.h.

        {
            std::string type_str;
            switch (reason_type)
            {
                case type::none:
                    type_str = "none";
                    break;
                case type::user_requested:
                    type_str = "user_requested";
                    break;
                case type::timeout:
                    type_str = "timeout";
                    break;
                case type::deadline:
                    type_str = "deadline";
                    break;
                case type::parent_cancelled:
                    type_str = "parent_cancelled";
                    break;
                case type::pool_shutdown:
                    type_str = "pool_shutdown";
                    break;
                case type::error:
                    type_str = "error";
                    break;
            }
 
            std::string result = "cancellation_reason{type=" + type_str;
            if (!message.empty())
            {
                result += ", message=\"" + message + "\"";
            }
            result += "}";
            return result;
        }

References deadline, error, message, none, parent_cancelled, pool_shutdown, reason_type, timeout, and user_requested.

◆ type_to_string()

static auto kcenon::thread::cancellation_reason::type_to_string ( type t ) -> std::string

inlinestaticnodiscard

Converts the reason type enum to a string.

Parameters

t	The reason type to convert.

Returns: A string representation of the reason type.

Definition at line 125 of file cancellation_reason.h.

        {
            switch (t)
            {
                case type::none:
                    return "none";
                case type::user_requested:
                    return "user_requested";
                case type::timeout:
                    return "timeout";
                case type::deadline:
                    return "deadline";
                case type::parent_cancelled:
                    return "parent_cancelled";
                case type::pool_shutdown:
                    return "pool_shutdown";
                case type::error:
                    return "error";
            }
            return "unknown";
        }

References deadline, error, none, parent_cancelled, pool_shutdown, timeout, and user_requested.

Member Data Documentation

◆ cancel_time

std::chrono::steady_clock::time_point kcenon::thread::cancellation_reason::cancel_time

Time point when the cancellation occurred.

Definition at line 74 of file cancellation_reason.h.

Referenced by kcenon::thread::enhanced_cancellation_token::create_linked(), kcenon::thread::enhanced_cancellation_token::create_linked_with_timeout(), kcenon::thread::enhanced_cancellation_token::do_cancel(), and kcenon::thread::enhanced_cancellation_token::start_timeout_timer().

◆ exception

std::optional<std::exception_ptr> kcenon::thread::cancellation_reason::exception

Optional exception that triggered the cancellation.

Definition at line 77 of file cancellation_reason.h.

Referenced by kcenon::thread::enhanced_cancellation_token::do_cancel().

◆ message

std::string kcenon::thread::cancellation_reason::message

Human-readable message describing the cancellation.

Definition at line 71 of file cancellation_reason.h.

Referenced by kcenon::thread::enhanced_cancellation_token::create_linked(), kcenon::thread::enhanced_cancellation_token::create_linked_with_timeout(), kcenon::thread::enhanced_cancellation_token::do_cancel(), kcenon::thread::operation_cancelled_exception::operation_cancelled_exception(), kcenon::thread::enhanced_cancellation_token::start_timeout_timer(), and to_string().

◆ reason_type

type kcenon::thread::cancellation_reason::reason_type = type::none

The type of cancellation that occurred.

Definition at line 68 of file cancellation_reason.h.

Referenced by kcenon::thread::enhanced_cancellation_token::create_linked(), kcenon::thread::enhanced_cancellation_token::create_linked_with_timeout(), kcenon::thread::enhanced_cancellation_token::do_cancel(), kcenon::thread::enhanced_cancellation_token::start_timeout_timer(), and to_string().

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

include/kcenon/thread/core/cancellation_reason.h

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes