enhanced_cancellation_token.h

Go to the documentation of this file.

// BSD 3-Clause License
// Copyright (c) 2024, 🍀☀🌕🌥 🌊
// See the LICENSE file in the project root for full license information.
 
#pragma once
 
#include "cancellation_exception.h"
#include "cancellation_reason.h"
#include "error_handling.h"
 
#include <atomic>
#include <chrono>
#include <condition_variable>
#include <functional>
#include <memory>
#include <mutex>
#include <optional>
#include <thread>
#include <unordered_map>
#include <vector>
 
namespace kcenon::thread
{
    // Forward declarations
    class enhanced_cancellation_token;
    class cancellation_callback_guard;
    class cancellation_scope;
    class cancellation_context;
 
    class enhanced_cancellation_token
    {
    public:
        // ====================================================================
        // Type definitions
        // ====================================================================
 
        using callback_handle = std::size_t;
 
        using callback_type = std::function<void()>;
 
        using callback_with_reason_type =
            std::function<void(const cancellation_reason&)>;
 
        // ====================================================================
        // Construction
        // ====================================================================
 
        enhanced_cancellation_token();
 
        enhanced_cancellation_token(const enhanced_cancellation_token&) = default;
 
        enhanced_cancellation_token(enhanced_cancellation_token&&) noexcept = default;
 
        auto operator=(const enhanced_cancellation_token&)
            -> enhanced_cancellation_token& = default;
 
        auto operator=(enhanced_cancellation_token&&) noexcept
            -> enhanced_cancellation_token& = default;
 
        ~enhanced_cancellation_token();
 
        [[nodiscard]] static auto create() -> enhanced_cancellation_token;
 
        [[nodiscard]] static auto create_with_timeout(std::chrono::milliseconds timeout)
            -> enhanced_cancellation_token;
 
        [[nodiscard]] static auto create_with_deadline(
            std::chrono::steady_clock::time_point deadline) -> enhanced_cancellation_token;
 
        [[nodiscard]] static auto create_linked(
            std::initializer_list<enhanced_cancellation_token> tokens)
            -> enhanced_cancellation_token;
 
        [[nodiscard]] static auto create_linked_with_timeout(
            const enhanced_cancellation_token& parent,
            std::chrono::milliseconds timeout) -> enhanced_cancellation_token;
 
        // ====================================================================
        // Cancellation
        // ====================================================================
 
        auto cancel() -> void;
 
        auto cancel(const std::string& message) -> void;
 
        auto cancel(std::exception_ptr ex) -> void;
 
        // ====================================================================
        // Query
        // ====================================================================
 
        [[nodiscard]] auto is_cancelled() const -> bool;
 
        [[nodiscard]] auto is_cancellation_requested() const -> bool;
 
        [[nodiscard]] auto get_reason() const -> std::optional<cancellation_reason>;
 
        [[nodiscard]] auto check_cancelled() const -> common::VoidResult;
 
        // ====================================================================
        // Timeout/Deadline
        // ====================================================================
 
        [[nodiscard]] auto has_timeout() const -> bool;
 
        [[nodiscard]] auto remaining_time() const -> std::chrono::milliseconds;
 
        [[nodiscard]] auto deadline() const -> std::chrono::steady_clock::time_point;
 
        auto extend_timeout(std::chrono::milliseconds additional) -> void;
 
        // ====================================================================
        // Callbacks
        // ====================================================================
 
        [[nodiscard]] auto register_callback(callback_type callback) -> callback_handle;
 
        [[nodiscard]] auto register_callback(callback_with_reason_type callback)
            -> callback_handle;
 
        auto unregister_callback(callback_handle handle) -> void;
 
        // ====================================================================
        // Waiting
        // ====================================================================
 
        auto wait() const -> void;
 
        [[nodiscard]] auto wait_for(std::chrono::milliseconds timeout) const -> bool;
 
        [[nodiscard]] auto wait_until(std::chrono::steady_clock::time_point deadline) const
            -> bool;
 
    private:
        struct state;
        std::shared_ptr<state> state_;
 
        explicit enhanced_cancellation_token(std::shared_ptr<state> state);
 
        auto do_cancel(cancellation_reason::type reason_type,
                       const std::string& message,
                       std::optional<std::exception_ptr> ex) -> void;
 
        static auto start_timeout_timer(std::weak_ptr<state> state_weak,
                                        std::chrono::steady_clock::time_point deadline)
            -> void;
    };
 
    class cancellation_callback_guard
    {
    public:
        cancellation_callback_guard(enhanced_cancellation_token& token,
                                    std::function<void()> callback);
 
        ~cancellation_callback_guard();
 
        // Non-copyable
        cancellation_callback_guard(const cancellation_callback_guard&) = delete;
        auto operator=(const cancellation_callback_guard&)
            -> cancellation_callback_guard& = delete;
 
        cancellation_callback_guard(cancellation_callback_guard&& other) noexcept;
 
        auto operator=(cancellation_callback_guard&& other) noexcept
            -> cancellation_callback_guard&;
 
    private:
        enhanced_cancellation_token* token_;
        enhanced_cancellation_token::callback_handle handle_;
    };
 
    class cancellation_scope
    {
    public:
        explicit cancellation_scope(enhanced_cancellation_token token);
 
        ~cancellation_scope() = default;
 
        // Non-copyable, non-movable
        cancellation_scope(const cancellation_scope&) = delete;
        auto operator=(const cancellation_scope&) -> cancellation_scope& = delete;
        cancellation_scope(cancellation_scope&&) = delete;
        auto operator=(cancellation_scope&&) -> cancellation_scope& = delete;
 
        [[nodiscard]] auto is_cancelled() const -> bool;
 
        [[nodiscard]] auto check_cancelled() const -> common::VoidResult;
 
        [[nodiscard]] auto token() const -> const enhanced_cancellation_token&;
 
    private:
        enhanced_cancellation_token token_;
    };
 
    class cancellation_context
    {
    public:
        [[nodiscard]] static auto current() -> enhanced_cancellation_token;
 
        static auto push(enhanced_cancellation_token token) -> void;
 
        static auto pop() -> void;
 
        class guard
        {
        public:
            explicit guard(enhanced_cancellation_token token);
 
            ~guard();
 
            // Non-copyable, non-movable
            guard(const guard&) = delete;
            auto operator=(const guard&) -> guard& = delete;
            guard(guard&&) = delete;
            auto operator=(guard&&) -> guard& = delete;
 
        private:
            bool pushed_;
        };
 
    private:
        cancellation_context() = delete;
    };
 
} // namespace kcenon::thread