kcenon::thread::cancellation_token Class Reference

Provides a mechanism for cooperative cancellation of operations. More...

#include <cancellation_token.h>

Collaboration diagram for kcenon::thread::cancellation_token:

Classes
struct	token_state

Public Member Functions
	cancellation_token ()
	cancellation_token (const cancellation_token &)=default
cancellation_token &	operator= (const cancellation_token &)=default
	cancellation_token (cancellation_token &&)=default
cancellation_token &	operator= (cancellation_token &&)=default
void	cancel ()
	Cancels the operation.
bool	is_cancelled () const
	Checks if the token has been canceled.
common::VoidResult	check_cancelled () const
	Checks if the token has been canceled and returns an error result.
void	register_callback (std::function< void()> callback)
	Registers a callback to be invoked when the token is canceled.
	cancellation_token ()
	cancellation_token (const cancellation_token &)=default
cancellation_token &	operator= (const cancellation_token &)=default
	cancellation_token (cancellation_token &&)=default
cancellation_token &	operator= (cancellation_token &&)=default
void	cancel ()
	Cancels the operation.
bool	is_cancelled () const
	Checks if the token has been canceled.
common::VoidResult	check_cancelled () const
	Checks if the token has been canceled and returns an error result.
void	register_callback (std::function< void()> callback)
	Registers a callback to be invoked when the token is canceled.

Static Public Member Functions
static cancellation_token	create ()
	Creates a new cancellation token.
static cancellation_token	create_linked (std::initializer_list< cancellation_token > tokens)
	Creates a linked token that is canceled when any of the parent tokens are canceled.
static cancellation_token	create ()
	Creates a new cancellation token.
static cancellation_token	create_linked (std::initializer_list< cancellation_token > tokens)
	Creates a linked token that is canceled when any of the parent tokens are canceled.

Private Member Functions
	cancellation_token (std::shared_ptr< token_state > state)
	cancellation_token (std::shared_ptr< token_state > state)

Private Attributes
std::shared_ptr< token_state >	state_

Detailed Description

Provides a mechanism for cooperative cancellation of operations.

Cancellation tokens allow long-running operations to be gracefully canceled. They are particularly useful for worker threads that need to be notified when their work should be aborted.

Definition at line 30 of file cancellation_token.h.

Constructor & Destructor Documentation

cancellation_token() [1/8]

kcenon::thread::cancellation_token::cancellation_token ( std::shared_ptr< token_state > state )

inlineexplicitprivate

Definition at line 42 of file cancellation_token.h.

        : state_(std::move(state)) {}

cancellation_token() [2/8]

kcenon::thread::cancellation_token::cancellation_token ( )

inline

Definition at line 47 of file cancellation_token.h.

: state_(std::make_shared<token_state>()) {}

Referenced by create().

Here is the caller graph for this function:

cancellation_token() [3/8]

kcenon::thread::cancellation_token::cancellation_token ( const cancellation_token & )

default

cancellation_token() [4/8]

kcenon::thread::cancellation_token::cancellation_token ( cancellation_token && )

default

cancellation_token() [5/8]

kcenon::thread::cancellation_token::cancellation_token ( std::shared_ptr< token_state > state )

inlineexplicitprivate

Definition at line 42 of file cancellation_token.h.

        : state_(std::move(state)) {}

cancellation_token() [6/8]

kcenon::thread::cancellation_token::cancellation_token ( )

inline

Definition at line 47 of file cancellation_token.h.

: state_(std::make_shared<token_state>()) {}

cancellation_token() [7/8]

kcenon::thread::cancellation_token::cancellation_token ( const cancellation_token & )

default

cancellation_token() [8/8]

kcenon::thread::cancellation_token::cancellation_token ( cancellation_token && )

default

Member Function Documentation

cancel() [1/2]

void kcenon::thread::cancellation_token::cancel ( )

inline

Cancels the operation.

Sets the token to the canceled state and invokes all registered callbacks.

Note

This method is thread-safe and guarantees callbacks are invoked exactly once.

Definition at line 107 of file cancellation_token.h.

                  {
        std::vector<std::function<void()>> callbacks_to_invoke;
        
        {
            std::lock_guard<std::mutex> lock(state_->callback_mutex);
            bool was_cancelled = state_->is_cancelled.exchange(true);
            if (!was_cancelled) {
                // Move callbacks to local vector to avoid holding lock during invocation
                callbacks_to_invoke = std::move(state_->callbacks);
                state_->callbacks.clear();
            }
        }
        
        // Invoke callbacks outside the lock to prevent deadlock
        for (const auto& callback : callbacks_to_invoke) {
            callback();
        }
    }

References kcenon::thread::callback, and state_.

Referenced by kcenon::thread::cancellable_future< R >::cancel(), kcenon::thread::cancellable_future< void >::cancel(), and kcenon::thread::thread_pool::stop_unsafe().

Here is the caller graph for this function:

cancel() [2/2]

void kcenon::thread::cancellation_token::cancel ( )

inline

Cancels the operation.

Sets the token to the canceled state and invokes all registered callbacks.

Memory Ordering:

• Uses memory_order_release to ensure all prior writes are visible to threads that subsequently observe the cancellation

Note

This method is thread-safe and guarantees callbacks are invoked exactly once.

Definition at line 111 of file cancellation_token.h.

                  {
        std::vector<std::function<void()>> callbacks_to_invoke;
 
        {
            std::lock_guard<std::mutex> lock(state_->callback_mutex);
            bool was_cancelled = state_->is_cancelled.exchange(true, std::memory_order_release);
            if (!was_cancelled) {
                // Move callbacks to local vector to avoid holding lock during invocation
                callbacks_to_invoke = std::move(state_->callbacks);
                state_->callbacks.clear();
            }
        }
 
        // Invoke callbacks outside the lock to prevent deadlock
        for (const auto& callback : callbacks_to_invoke) {
            callback();
        }
    }

References kcenon::thread::callback, and state_.

check_cancelled() [1/2]

common::VoidResult kcenon::thread::cancellation_token::check_cancelled ( ) const

inlinenodiscard

Checks if the token has been canceled and returns an error result.

Returns

common::VoidResult — error with operation_canceled if cancelled, success otherwise

Definition at line 139 of file cancellation_token.h.

                                                           {
        if (is_cancelled()) {
            return make_error_result(error_code::operation_canceled);
        }
        return common::ok();
    }

References is_cancelled(), kcenon::thread::make_error_result(), and kcenon::thread::operation_canceled.

Here is the call graph for this function:

check_cancelled() [2/2]

common::VoidResult kcenon::thread::cancellation_token::check_cancelled ( ) const

inlinenodiscard

Checks if the token has been canceled and returns an error result.

Returns

common::VoidResult — error with operation_canceled if cancelled, success otherwise

Definition at line 148 of file cancellation_token.h.

                                                           {
        if (is_cancelled()) {
            return make_error_result(error_code::operation_canceled);
        }
        return common::ok();
    }

References is_cancelled(), kcenon::thread::make_error_result(), and kcenon::thread::operation_canceled.

Here is the call graph for this function:

create() [1/2]

static cancellation_token kcenon::thread::cancellation_token::create ( )

inlinestatic

Creates a new cancellation token.

Returns

A new cancellation token

Definition at line 59 of file cancellation_token.h.

                                       {
        return cancellation_token();
    }

References cancellation_token().

Referenced by create_linked(), and kcenon::thread::thread_pool::start().

Here is the call graph for this function:

Here is the caller graph for this function:

create() [2/2]

static cancellation_token kcenon::thread::cancellation_token::create ( )

inlinestatic

Creates a new cancellation token.

Returns

A new cancellation token

Definition at line 59 of file cancellation_token.h.

                                       {
        return cancellation_token();
    }

References cancellation_token().

Here is the call graph for this function:

create_linked() [1/2]

static cancellation_token kcenon::thread::cancellation_token::create_linked ( std::initializer_list< cancellation_token > tokens )

inlinestatic

Creates a linked token that is canceled when any of the parent tokens are canceled.

Parameters

tokens

The parent tokens

Returns

A new token linked to the parents

Note

Uses weak_ptr to avoid circular references and memory leaks

Definition at line 70 of file cancellation_token.h.

                                                                                            {
        auto new_token = create();
        auto new_state_weak = std::weak_ptr<token_state>(new_token.state_);
        
        for (const auto& token : tokens) {
            auto token_copy = token;
            token_copy.register_callback([new_state_weak]() {
                if (auto state = new_state_weak.lock()) {
                    // Directly set the cancelled flag and invoke callbacks
                    std::vector<std::function<void()>> callbacks_to_invoke;
                    
                    {
                        std::lock_guard<std::mutex> lock(state->callback_mutex);
                        bool was_cancelled = state->is_cancelled.exchange(true);
                        if (!was_cancelled) {
                            callbacks_to_invoke = std::move(state->callbacks);
                            state->callbacks.clear();
                        }
                    }
                    
                    for (const auto& callback : callbacks_to_invoke) {
                        callback();
                    }
                }
            });
        }
        
        return new_token;
    }

References kcenon::thread::callback, and create().

Here is the call graph for this function:

create_linked() [2/2]

static cancellation_token kcenon::thread::cancellation_token::create_linked ( std::initializer_list< cancellation_token > tokens )

inlinestatic

Creates a linked token that is canceled when any of the parent tokens are canceled.

Parameters

tokens

The parent tokens

Returns

A new token linked to the parents

Note

Uses weak_ptr to avoid circular references and memory leaks

Definition at line 70 of file cancellation_token.h.

                                                                                            {
        auto new_token = create();
        auto new_state_weak = std::weak_ptr<token_state>(new_token.state_);
        
        for (const auto& token : tokens) {
            auto token_copy = token;
            token_copy.register_callback([new_state_weak]() {
                if (auto state = new_state_weak.lock()) {
                    // Directly set the cancelled flag and invoke callbacks
                    std::vector<std::function<void()>> callbacks_to_invoke;
 
                    {
                        std::lock_guard<std::mutex> lock(state->callback_mutex);
                        bool was_cancelled = state->is_cancelled.exchange(true, std::memory_order_release);
                        if (!was_cancelled) {
                            callbacks_to_invoke = std::move(state->callbacks);
                            state->callbacks.clear();
                        }
                    }
 
                    for (const auto& callback : callbacks_to_invoke) {
                        callback();
                    }
                }
            });
        }
        
        return new_token;
    }

References kcenon::thread::callback, and create().

Here is the call graph for this function:

is_cancelled() [1/2]

bool kcenon::thread::cancellation_token::is_cancelled ( ) const

inlinenodiscard

Checks if the token has been canceled.

Returns

true if the token has been canceled, false otherwise

Examples

/home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h, and job_cancellation_example.cpp.

Definition at line 130 of file cancellation_token.h.

                                            {
        return state_->is_cancelled.load();
    }

References state_.

Referenced by check_cancelled(), cancellable_long_job::do_work(), kcenon::thread::future_job< R >::do_work(), kcenon::thread::job_builder::built_job::do_work(), kcenon::thread::cancellable_future< R >::get(), kcenon::thread::cancellable_future< void >::get(), kcenon::thread::cancellable_future< R >::get_for(), kcenon::thread::cancellable_future< void >::get_for(), kcenon::thread::cancellable_future< R >::is_cancelled(), and kcenon::thread::cancellable_future< void >::is_cancelled().

Here is the caller graph for this function:

is_cancelled() [2/2]

bool kcenon::thread::cancellation_token::is_cancelled ( ) const

inlinenodiscard

Checks if the token has been canceled.

Memory Ordering:

• Uses memory_order_acquire to ensure proper synchronization with the cancellation thread's release operation

Returns

true if the token has been canceled, false otherwise

Definition at line 139 of file cancellation_token.h.

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

References state_.

operator=() [1/4]

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

default

operator=() [2/4]

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

default

operator=() [3/4]

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

default

operator=() [4/4]

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

default

register_callback() [1/2]

void kcenon::thread::cancellation_token::register_callback ( std::function< void()> callback )

inline

Registers a callback to be invoked when the token is canceled.

Parameters

callback

The function to call when the token is canceled

If the token is already canceled, the callback is invoked immediately.

Note

This method is thread-safe and guarantees the callback is called exactly once.

Definition at line 154 of file cancellation_token.h.

                                                         {
        std::unique_lock<std::mutex> lock(state_->callback_mutex);
        
        // Check cancellation state while holding the lock
        if (state_->is_cancelled.load()) {
            lock.unlock();
            callback();
            return;
        }
        
        // Add callback while still holding the lock
        state_->callbacks.push_back(std::move(callback));
    }

References kcenon::thread::callback, and state_.

register_callback() [2/2]

void kcenon::thread::cancellation_token::register_callback ( std::function< void()> callback )

inline

Registers a callback to be invoked when the token is canceled.

Parameters

callback

The function to call when the token is canceled

If the token is already canceled, the callback is invoked immediately.

Memory Ordering:

• Uses memory_order_acquire when checking cancellation status to synchronize with the cancel() operation

Note

This method is thread-safe and guarantees the callback is called exactly once.

Definition at line 167 of file cancellation_token.h.

                                                         {
        std::unique_lock<std::mutex> lock(state_->callback_mutex);
 
        // Check cancellation state while holding the lock
        if (state_->is_cancelled.load(std::memory_order_acquire)) {
            lock.unlock();
            callback();
            return;
        }
 
        // Add callback while still holding the lock
        state_->callbacks.push_back(std::move(callback));
    }

References kcenon::thread::callback, and state_.

Member Data Documentation

state_

std::shared_ptr< token_state > kcenon::thread::cancellation_token::state_

private

Definition at line 39 of file cancellation_token.h.

Referenced by cancel(), is_cancelled(), and register_callback().

---

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

• core/sync/include/cancellation_token.h
• include/kcenon/thread/core/cancellation_token.h