task_scheduler.h

Go to the documentation of this file.

// BSD 3-Clause License
// Copyright (c) 2021-2025, 🍀☀🌕🌥 🌊
// See the LICENSE file in the project root for full license information.
 
#pragma once
 
#include "task_scheduler_config.h"
 
#include <atomic>
#include <chrono>
#include <condition_variable>
#include <functional>
#include <map>
#include <memory>
#include <mutex>
#include <optional>
#include <queue>
#include <string>
#include <thread>
#include <vector>
 
// Forward declarations for kcenon ecosystem
namespace kcenon::thread {
class thread_pool;
}  // namespace kcenon::thread
 
namespace kcenon::common::interfaces {
class IExecutor;
}  // namespace kcenon::common::interfaces
 
// Forward declarations for PACS modules
namespace kcenon::pacs::storage {
class index_database;
class file_storage;
}  // namespace kcenon::pacs::storage
 
namespace kcenon::pacs::workflow {
 
// Forward declare Result type (defined in integration or common)
template <typename T>
class Result;
 
class task_scheduler {
public:
    // =========================================================================
    // Construction
    // =========================================================================
 
    explicit task_scheduler(
        storage::index_database& database,
        const task_scheduler_config& config = {});
 
    task_scheduler(
        storage::index_database& database,
        storage::file_storage& file_storage,
        std::shared_ptr<kcenon::thread::thread_pool> thread_pool,
        const task_scheduler_config& config = {});
 
    task_scheduler(
        storage::index_database& database,
        storage::file_storage& file_storage,
        std::shared_ptr<kcenon::common::interfaces::IExecutor> executor,
        const task_scheduler_config& config = {});
 
    ~task_scheduler();
 
    task_scheduler(const task_scheduler&) = delete;
    task_scheduler& operator=(const task_scheduler&) = delete;
 
    task_scheduler(task_scheduler&&) = delete;
    task_scheduler& operator=(task_scheduler&&) = delete;
 
    // =========================================================================
    // Lifecycle Management
    // =========================================================================
 
    void start();
 
    void stop(bool wait_for_completion = true);
 
    [[nodiscard]] auto is_running() const noexcept -> bool;
 
    // =========================================================================
    // Task Scheduling - Cleanup
    // =========================================================================
 
    auto schedule_cleanup(const cleanup_config& config) -> task_id;
 
    // =========================================================================
    // Task Scheduling - Archive
    // =========================================================================
 
    auto schedule_archive(const archive_config& config) -> task_id;
 
    // =========================================================================
    // Task Scheduling - Verification
    // =========================================================================
 
    auto schedule_verification(const verification_config& config) -> task_id;
 
    // =========================================================================
    // Task Scheduling - Custom
    // =========================================================================
 
    auto schedule(
        const std::string& name,
        const std::string& description,
        std::chrono::seconds interval,
        task_callback_with_result callback) -> task_id;
 
    auto schedule(
        const std::string& name,
        const std::string& description,
        const cron_schedule& cron_expr,
        task_callback_with_result callback) -> task_id;
 
    auto schedule_once(
        const std::string& name,
        const std::string& description,
        std::chrono::system_clock::time_point execute_at,
        task_callback_with_result callback) -> task_id;
 
    auto schedule(scheduled_task task) -> task_id;
 
    // =========================================================================
    // Task Management
    // =========================================================================
 
    [[nodiscard]] auto list_tasks() const -> std::vector<scheduled_task>;
 
    [[nodiscard]] auto list_tasks(task_type type) const
        -> std::vector<scheduled_task>;
 
    [[nodiscard]] auto list_tasks(task_state state) const
        -> std::vector<scheduled_task>;
 
    [[nodiscard]] auto get_task(const task_id& id) const
        -> std::optional<scheduled_task>;
 
    auto cancel_task(const task_id& id) -> bool;
 
    auto pause_task(const task_id& id) -> bool;
 
    auto resume_task(const task_id& id) -> bool;
 
    auto trigger_task(const task_id& id) -> bool;
 
    auto update_schedule(const task_id& id, const kcenon::pacs::workflow::schedule& new_schedule) -> bool;
 
    // =========================================================================
    // Execution History
    // =========================================================================
 
    [[nodiscard]] auto get_execution_history(
        const task_id& id,
        std::size_t limit = 100) const -> std::vector<task_execution_record>;
 
    [[nodiscard]] auto get_recent_executions(std::size_t limit = 100) const
        -> std::vector<task_execution_record>;
 
    void clear_history(const task_id& id, std::size_t keep_last = 0);
 
    // =========================================================================
    // Statistics and Monitoring
    // =========================================================================
 
    [[nodiscard]] auto get_stats() const -> scheduler_stats;
 
    [[nodiscard]] auto pending_count() const noexcept -> std::size_t;
 
    [[nodiscard]] auto running_count() const noexcept -> std::size_t;
 
    // =========================================================================
    // Persistence
    // =========================================================================
 
    auto save_tasks() const -> bool;
 
    auto load_tasks() -> std::size_t;
 
    // =========================================================================
    // Configuration
    // =========================================================================
 
    void set_task_complete_callback(
        task_scheduler_config::task_complete_callback callback);
 
    void set_error_callback(
        task_scheduler_config::task_error_callback callback);
 
private:
    // =========================================================================
    // Internal Methods
    // =========================================================================
 
    void run_loop();
 
    void execute_cycle();
 
    auto execute_task(scheduled_task& task) -> task_execution_record;
 
    [[nodiscard]] auto calculate_next_run(
        const kcenon::pacs::workflow::schedule& sched,
        std::chrono::system_clock::time_point from =
            std::chrono::system_clock::now()) const
        -> std::optional<std::chrono::system_clock::time_point>;
 
    [[nodiscard]] auto calculate_next_cron_run(
        const cron_schedule& cron,
        std::chrono::system_clock::time_point from) const
        -> std::optional<std::chrono::system_clock::time_point>;
 
    [[nodiscard]] auto generate_task_id() const -> task_id;
 
    [[nodiscard]] auto generate_execution_id() const -> std::string;
 
    [[nodiscard]] auto create_cleanup_callback(const cleanup_config& config)
        -> task_callback_with_result;
 
    [[nodiscard]] auto create_archive_callback(const archive_config& config)
        -> task_callback_with_result;
 
    [[nodiscard]] auto create_verification_callback(const verification_config& config)
        -> task_callback_with_result;
 
    void record_execution(const task_id& task_id,
                         const task_execution_record& record);
 
    void update_stats(const task_execution_record& record);
 
    [[nodiscard]] auto serialize_tasks() const -> std::string;
 
    auto deserialize_tasks(const std::string& json) -> std::size_t;
 
    // =========================================================================
    // Member Variables
    // =========================================================================
 
    storage::index_database& database_;
 
    storage::file_storage* file_storage_{nullptr};
 
    std::shared_ptr<kcenon::thread::thread_pool> thread_pool_;
 
    std::shared_ptr<kcenon::common::interfaces::IExecutor> executor_;
 
    task_scheduler_config config_;
 
    std::thread scheduler_thread_;
 
    mutable std::mutex mutex_;
 
    std::condition_variable cv_;
 
    std::atomic<bool> stop_requested_{false};
 
    std::atomic<bool> running_{false};
 
    std::map<task_id, scheduled_task> tasks_;
 
    mutable std::mutex tasks_mutex_;
 
    std::map<task_id, std::vector<task_execution_record>> execution_history_;
 
    mutable std::mutex history_mutex_;
 
    std::atomic<std::size_t> running_count_{0};
 
    scheduler_stats stats_;
 
    mutable std::mutex stats_mutex_;
 
    std::chrono::steady_clock::time_point start_time_;
 
    mutable std::atomic<uint64_t> next_task_id_{1};
 
    mutable std::atomic<uint64_t> next_execution_id_{1};
};
 
}  // namespace kcenon::pacs::workflow