study_lock_manager.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 <atomic>
#include <chrono>
#include <cstdint>
#include <functional>
#include <map>
#include <memory>
#include <mutex>
#include <optional>
#include <shared_mutex>
#include <string>
#include <vector>
 
// Forward declarations for kcenon ecosystem
namespace kcenon::common {
template <typename T>
class Result;
struct error_info;
}  // namespace kcenon::common
 
namespace kcenon::pacs::workflow {
 
// =============================================================================
// Lock Types and Configuration
// =============================================================================
 
enum class lock_type {
    exclusive,  
    shared,     
    migration   
};
 
[[nodiscard]] inline auto to_string(lock_type type) -> std::string {
    switch (type) {
        case lock_type::exclusive: return "exclusive";
        case lock_type::shared: return "shared";
        case lock_type::migration: return "migration";
        default: return "unknown";
    }
}
 
[[nodiscard]] inline auto parse_lock_type(const std::string& str)
    -> std::optional<lock_type> {
    if (str == "exclusive") return lock_type::exclusive;
    if (str == "shared") return lock_type::shared;
    if (str == "migration") return lock_type::migration;
    return std::nullopt;
}
 
// =============================================================================
// Lock Token and Information
// =============================================================================
 
struct lock_token {
    std::string token_id;
 
    std::string study_uid;
 
    lock_type type{lock_type::exclusive};
 
    std::chrono::system_clock::time_point acquired_at;
 
    std::optional<std::chrono::system_clock::time_point> expires_at;
 
    [[nodiscard]] auto is_valid() const -> bool {
        if (!expires_at) return true;
        return std::chrono::system_clock::now() < *expires_at;
    }
 
    [[nodiscard]] auto is_expired() const -> bool {
        return !is_valid();
    }
 
    [[nodiscard]] auto remaining_time() const
        -> std::optional<std::chrono::milliseconds> {
        if (!expires_at) return std::nullopt;
        auto now = std::chrono::system_clock::now();
        if (now >= *expires_at) return std::chrono::milliseconds{0};
        return std::chrono::duration_cast<std::chrono::milliseconds>(
            *expires_at - now);
    }
};
 
struct lock_info {
    std::string study_uid;
 
    lock_type type{lock_type::exclusive};
 
    std::string reason;
 
    std::string holder;
 
    std::string token_id;
 
    std::chrono::system_clock::time_point acquired_at;
 
    std::optional<std::chrono::system_clock::time_point> expires_at;
 
    std::size_t shared_count{0};
 
    [[nodiscard]] auto duration() const -> std::chrono::milliseconds {
        return std::chrono::duration_cast<std::chrono::milliseconds>(
            std::chrono::system_clock::now() - acquired_at);
    }
 
    [[nodiscard]] auto is_expired() const -> bool {
        if (!expires_at) return false;
        return std::chrono::system_clock::now() >= *expires_at;
    }
};
 
// =============================================================================
// Lock Manager Configuration
// =============================================================================
 
struct study_lock_manager_config {
    std::chrono::seconds default_timeout{0};
 
    std::chrono::milliseconds acquire_wait_timeout{5000};
 
    std::chrono::seconds cleanup_interval{60};
 
    bool auto_cleanup{true};
 
    std::size_t max_shared_locks{100};
 
    bool allow_force_unlock{true};
};
 
// =============================================================================
// Lock Statistics
// =============================================================================
 
struct lock_manager_stats {
    std::size_t active_locks{0};
 
    std::size_t exclusive_locks{0};
 
    std::size_t shared_locks{0};
 
    std::size_t migration_locks{0};
 
    std::size_t total_acquisitions{0};
 
    std::size_t total_releases{0};
 
    std::size_t timeout_count{0};
 
    std::size_t force_unlock_count{0};
 
    std::chrono::milliseconds avg_lock_duration{0};
 
    std::chrono::milliseconds max_lock_duration{0};
 
    std::size_t contention_count{0};
};
 
// =============================================================================
// Error Codes
// =============================================================================
 
namespace lock_error {
    constexpr int already_locked = -100;
 
    constexpr int not_found = -101;
 
    constexpr int invalid_token = -102;
 
    constexpr int timeout = -103;
 
    constexpr int expired = -104;
 
    constexpr int permission_denied = -105;
 
    constexpr int invalid_type = -106;
 
    constexpr int max_shared_exceeded = -107;
 
    constexpr int upgrade_failed = -108;
}  // namespace lock_error
 
// =============================================================================
// Study Lock Manager Class
// =============================================================================
 
class study_lock_manager {
public:
    // =========================================================================
    // Construction
    // =========================================================================
 
    study_lock_manager();
 
    explicit study_lock_manager(const study_lock_manager_config& config);
 
    ~study_lock_manager();
 
    study_lock_manager(const study_lock_manager&) = delete;
    study_lock_manager& operator=(const study_lock_manager&) = delete;
 
    study_lock_manager(study_lock_manager&&) noexcept;
    study_lock_manager& operator=(study_lock_manager&&) noexcept;
 
    // =========================================================================
    // Lock Acquisition
    // =========================================================================
 
    [[nodiscard]] auto lock(
        const std::string& study_uid,
        const std::string& reason,
        const std::string& holder = "",
        std::chrono::seconds timeout = std::chrono::seconds{0})
        -> kcenon::common::Result<lock_token>;
 
    [[nodiscard]] auto lock(
        const std::string& study_uid,
        lock_type type,
        const std::string& reason,
        const std::string& holder = "",
        std::chrono::seconds timeout = std::chrono::seconds{0})
        -> kcenon::common::Result<lock_token>;
 
    [[nodiscard]] auto try_lock(
        const std::string& study_uid,
        lock_type type,
        const std::string& reason,
        const std::string& holder = "",
        std::chrono::seconds timeout = std::chrono::seconds{0})
        -> kcenon::common::Result<lock_token>;
 
    // =========================================================================
    // Lock Release
    // =========================================================================
 
    [[nodiscard]] auto unlock(const lock_token& token)
        -> kcenon::common::Result<std::monostate>;
 
    [[nodiscard]] auto unlock(
        const std::string& study_uid,
        const std::string& holder)
        -> kcenon::common::Result<std::monostate>;
 
    [[nodiscard]] auto force_unlock(
        const std::string& study_uid,
        const std::string& admin_reason = "")
        -> kcenon::common::Result<std::monostate>;
 
    auto unlock_all_by_holder(const std::string& holder) -> std::size_t;
 
    // =========================================================================
    // Lock Status
    // =========================================================================
 
    [[nodiscard]] auto is_locked(const std::string& study_uid) const -> bool;
 
    [[nodiscard]] auto is_locked(
        const std::string& study_uid,
        lock_type type) const -> bool;
 
    [[nodiscard]] auto get_lock_info(const std::string& study_uid) const
        -> std::optional<lock_info>;
 
    [[nodiscard]] auto get_lock_info_by_token(const std::string& token_id) const
        -> std::optional<lock_info>;
 
    [[nodiscard]] auto validate_token(const lock_token& token) const -> bool;
 
    [[nodiscard]] auto refresh_lock(
        const lock_token& token,
        std::chrono::seconds extension = std::chrono::seconds{0})
        -> kcenon::common::Result<lock_token>;
 
    // =========================================================================
    // Lock Queries
    // =========================================================================
 
    [[nodiscard]] auto get_all_locks() const -> std::vector<lock_info>;
 
    [[nodiscard]] auto get_locks_by_holder(const std::string& holder) const
        -> std::vector<lock_info>;
 
    [[nodiscard]] auto get_locks_by_type(lock_type type) const
        -> std::vector<lock_info>;
 
    [[nodiscard]] auto get_expired_locks() const -> std::vector<lock_info>;
 
    // =========================================================================
    // Maintenance
    // =========================================================================
 
    auto cleanup_expired_locks() -> std::size_t;
 
    [[nodiscard]] auto get_stats() const -> lock_manager_stats;
 
    void reset_stats();
 
    [[nodiscard]] auto get_config() const -> const study_lock_manager_config&;
 
    void set_config(const study_lock_manager_config& config);
 
    // =========================================================================
    // Event Callbacks
    // =========================================================================
 
    using lock_event_callback = std::function<void(
        const std::string& study_uid,
        const lock_info& info)>;
 
    void set_on_lock_acquired(lock_event_callback callback);
 
    void set_on_lock_released(lock_event_callback callback);
 
    void set_on_lock_expired(lock_event_callback callback);
 
private:
    // =========================================================================
    // Internal Types
    // =========================================================================
 
    struct lock_entry {
        lock_info info;
        std::vector<std::string> shared_holders;  // For shared locks
    };
 
    // =========================================================================
    // Internal Methods
    // =========================================================================
 
    [[nodiscard]] auto generate_token_id() const -> std::string;
 
    [[nodiscard]] auto resolve_holder(const std::string& holder) const
        -> std::string;
 
    [[nodiscard]] auto calculate_expiry(std::chrono::seconds timeout) const
        -> std::optional<std::chrono::system_clock::time_point>;
 
    [[nodiscard]] auto can_acquire_lock(
        const std::string& study_uid,
        lock_type type) const -> bool;
 
    void record_acquisition(lock_type type);
 
    void record_release(lock_type type, std::chrono::milliseconds duration);
 
    // =========================================================================
    // Member Variables
    // =========================================================================
 
    study_lock_manager_config config_;
 
    std::map<std::string, lock_entry> locks_;
 
    std::map<std::string, std::string> token_to_study_;
 
    mutable std::shared_mutex mutex_;
 
    mutable lock_manager_stats stats_;
 
    mutable std::mutex stats_mutex_;
 
    mutable std::atomic<uint64_t> next_token_id_{1};
 
    lock_event_callback on_lock_acquired_;
    lock_event_callback on_lock_released_;
    lock_event_callback on_lock_expired_;
};
 
}  // namespace kcenon::pacs::workflow