kcenon::pacs::workflow::study_lock_manager Class Reference

Manages locks on DICOM studies for concurrent access control. More...

#include <study_lock_manager.h>

Collaboration diagram for kcenon::pacs::workflow::study_lock_manager:

Classes
struct	lock_entry

Public Types
using	lock_event_callback
	Callback type for lock events.

Public Member Functions
	study_lock_manager ()
	Construct lock manager with default configuration.
	study_lock_manager (const study_lock_manager_config &config)
	Construct lock manager with custom configuration.
	~study_lock_manager ()
	Destructor - releases all locks.
	study_lock_manager (const study_lock_manager &)=delete
	Non-copyable.
study_lock_manager &	operator= (const study_lock_manager &)=delete
	study_lock_manager (study_lock_manager &&) noexcept
	Movable.
study_lock_manager &	operator= (study_lock_manager &&) noexcept
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 >
	Acquire an exclusive lock on a study.
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 >
	Acquire a lock of specific type on a study.
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 >
	Try to acquire a lock without blocking.
auto	unlock (const lock_token &token) -> kcenon::common::Result< std::monostate >
	Release a lock using its token.
auto	unlock (const std::string &study_uid, const std::string &holder) -> kcenon::common::Result< std::monostate >
	Release a lock by study UID and holder.
auto	force_unlock (const std::string &study_uid, const std::string &admin_reason="") -> kcenon::common::Result< std::monostate >
	Force release a lock (admin operation)
auto	unlock_all_by_holder (const std::string &holder) -> std::size_t
	Release all locks held by a specific holder.
auto	is_locked (const std::string &study_uid) const -> bool
	Check if a study is locked.
auto	is_locked (const std::string &study_uid, lock_type type) const -> bool
	Check if a study has a specific lock type.
auto	get_lock_info (const std::string &study_uid) const -> std::optional< lock_info >
	Get lock information for a study.
auto	get_lock_info_by_token (const std::string &token_id) const -> std::optional< lock_info >
	Get lock information by token ID.
auto	validate_token (const lock_token &token) const -> bool
	Validate a lock token.
auto	refresh_lock (const lock_token &token, std::chrono::seconds extension=std::chrono::seconds{0}) -> kcenon::common::Result< lock_token >
	Refresh a lock (extend its timeout)
auto	get_all_locks () const -> std::vector< lock_info >
	Get all currently held locks.
auto	get_locks_by_holder (const std::string &holder) const -> std::vector< lock_info >
	Get all locks held by a specific holder.
auto	get_locks_by_type (lock_type type) const -> std::vector< lock_info >
	Get all locks of a specific type.
auto	get_expired_locks () const -> std::vector< lock_info >
	Get all expired locks.
auto	cleanup_expired_locks () -> std::size_t
	Clean up expired locks.
auto	get_stats () const -> lock_manager_stats
	Get lock manager statistics.
void	reset_stats ()
	Reset statistics counters.
auto	get_config () const -> const study_lock_manager_config &
	Get the current configuration.
void	set_config (const study_lock_manager_config &config)
	Update configuration.
void	set_on_lock_acquired (lock_event_callback callback)
	Set callback for lock acquisition events.
void	set_on_lock_released (lock_event_callback callback)
	Set callback for lock release events.
void	set_on_lock_expired (lock_event_callback callback)
	Set callback for lock expiration events.

Private Member Functions
auto	generate_token_id () const -> std::string
	Generate a unique token ID.
auto	resolve_holder (const std::string &holder) const -> std::string
	Get holder identifier (uses thread ID if empty)
auto	calculate_expiry (std::chrono::seconds timeout) const -> std::optional< std::chrono::system_clock::time_point >
	Calculate expiration time.
auto	can_acquire_lock (const std::string &study_uid, lock_type type) const -> bool
	Check if a lock can be acquired.
void	record_acquisition (lock_type type)
	Update statistics on lock acquisition.
void	record_release (lock_type type, std::chrono::milliseconds duration)
	Update statistics on lock release.

Private Attributes
study_lock_manager_config	config_
	Configuration.
std::map< std::string, lock_entry >	locks_
	Lock entries (study_uid -> lock_entry)
std::map< std::string, std::string >	token_to_study_
	Token to study UID mapping for fast lookup.
std::shared_mutex	mutex_
	Mutex for thread-safe access.
lock_manager_stats	stats_
	Statistics.
std::mutex	stats_mutex_
	Mutex for statistics.
std::atomic< uint64_t >	next_token_id_ {1}
	Next token ID counter.
lock_event_callback	on_lock_acquired_
	Event callbacks.
lock_event_callback	on_lock_released_
lock_event_callback	on_lock_expired_

Detailed Description

Manages locks on DICOM studies for concurrent access control.

The study_lock_manager provides thread-safe locking mechanisms for DICOM studies to prevent concurrent modifications and ensure data integrity.

Key Features

• Exclusive Locks: Prevent all other access to a study
• Shared Locks: Allow concurrent read access
• Migration Locks: High-priority locks for migration operations
• Automatic Timeout: Locks can expire after a configured duration
• Force Unlock: Admin capability to forcibly release locks

Integration with kcenon Ecosystem

• thread_system: Thread-safe operations via shared_mutex
• logger_system: Audit trails for lock operations
• monitoring_system: Lock contention and duration metrics
• common_system: Result<T> for error handling

Lock Priority

When multiple lock requests compete:

1. Migration locks have highest priority
2. Exclusive locks block new shared locks
3. Shared locks can coexist with other shared locks

Definition at line 337 of file study_lock_manager.h.

Member Typedef Documentation

lock_event_callback

using kcenon::pacs::workflow::study_lock_manager::lock_event_callback

Initial value:

 std::function<void(
        const std::string& study_uid,
        const lock_info& info)>

Callback type for lock events.

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 610 of file study_lock_manager.h.

Constructor & Destructor Documentation

study_lock_manager() [1/4]

kcenon::pacs::workflow::study_lock_manager::study_lock_manager

(

)

Construct lock manager with default configuration.

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 26 of file study_lock_manager.cpp.

    : config_{} {}

study_lock_manager() [2/4]

kcenon::pacs::workflow::study_lock_manager::study_lock_manager ( const study_lock_manager_config & config )

explicit

Construct lock manager with custom configuration.

Parameters

config

Lock manager configuration

Definition at line 29 of file study_lock_manager.cpp.

    : config_{config} {}

~study_lock_manager()

kcenon::pacs::workflow::study_lock_manager::~study_lock_manager

(

)

Destructor - releases all locks.

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 32 of file study_lock_manager.cpp.

                                        {
    // Release all locks on destruction
    std::unique_lock lock{mutex_};
    locks_.clear();
    token_to_study_.clear();
}

References lock(), locks_, mutex_, and token_to_study_.

Here is the call graph for this function:

study_lock_manager() [3/4]

kcenon::pacs::workflow::study_lock_manager::study_lock_manager ( const study_lock_manager & )

delete

Non-copyable.

study_lock_manager() [4/4]

kcenon::pacs::workflow::study_lock_manager::study_lock_manager ( study_lock_manager && other )

noexcept

Movable.

Definition at line 39 of file study_lock_manager.cpp.

    : config_{std::move(other.config_)},
      locks_{std::move(other.locks_)},
      token_to_study_{std::move(other.token_to_study_)},
      stats_{std::move(other.stats_)},
      next_token_id_{other.next_token_id_.load()},
      on_lock_acquired_{std::move(other.on_lock_acquired_)},
      on_lock_released_{std::move(other.on_lock_released_)},
      on_lock_expired_{std::move(other.on_lock_expired_)} {}

Member Function Documentation

calculate_expiry()

auto kcenon::pacs::workflow::study_lock_manager::calculate_expiry ( std::chrono::seconds timeout ) const -> std::optional<std::chrono::system_clock::time_point>

nodiscardprivate

Calculate expiration time.

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 813 of file study_lock_manager.cpp.

                                                    {
    auto effective_timeout = timeout.count() > 0 ? timeout : config_.default_timeout;
    if (effective_timeout.count() <= 0) {
        return std::nullopt;  // No expiration
    }
 
    return std::chrono::system_clock::now() + effective_timeout;
}

can_acquire_lock()

auto kcenon::pacs::workflow::study_lock_manager::can_acquire_lock ( const std::string & study_uid, lock_type type ) const -> bool

nodiscardprivate

Check if a lock can be acquired.

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 823 of file study_lock_manager.cpp.

                                  {
    auto it = locks_.find(study_uid);
    if (it == locks_.end()) {
        return true;
    }
 
    if (it->second.info.is_expired()) {
        return true;
    }
 
    // Shared locks can coexist with other shared locks
    if (type == lock_type::shared &&
        it->second.info.type == lock_type::shared) {
        return it->second.shared_holders.size() < config_.max_shared_locks;
    }
 
    return false;
}

References kcenon::pacs::workflow::shared.

cleanup_expired_locks()

auto kcenon::pacs::workflow::study_lock_manager::cleanup_expired_locks

(

)

-> std::size_t

Clean up expired locks.

Returns

Number of expired locks cleaned up

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 687 of file study_lock_manager.cpp.

                                                            {
    std::unique_lock lock{mutex_};
 
    std::vector<std::string> expired_studies;
 
    for (const auto& [study_uid, entry] : locks_) {
        if (entry.info.is_expired()) {
            expired_studies.push_back(study_uid);
        }
    }
 
    for (const auto& study_uid : expired_studies) {
        auto it = locks_.find(study_uid);
        if (it != locks_.end()) {
            lock_info expired_info = it->second.info;
 
            // Remove token mapping
            auto token_it = token_to_study_.find(it->second.info.token_id);
            if (token_it != token_to_study_.end()) {
                token_to_study_.erase(token_it);
            }
 
            locks_.erase(it);
 
            if (on_lock_expired_) {
                lock.unlock();
                on_lock_expired_(study_uid, expired_info);
                lock.lock();
            }
        }
    }
 
    return expired_studies.size();
}

force_unlock()

auto kcenon::pacs::workflow::study_lock_manager::force_unlock ( const std::string & study_uid, const std::string & admin_reason = "" ) -> kcenon::common::Result<std::monostate>

nodiscard

Force release a lock (admin operation)

Parameters

study_uid	Study UID to unlock
admin_reason	Reason for force unlock

Returns

Result indicating success or error

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 366 of file study_lock_manager.cpp.

                                        {
    // Note: admin_reason can be used for audit logging in future
    if (!config_.allow_force_unlock) {
        return kcenon::common::Result<std::monostate>::err(
            kcenon::common::error_info{
                lock_error::permission_denied,
                "Force unlock is not allowed",
                "study_lock_manager"});
    }
 
    std::unique_lock lock{mutex_};
 
    auto lock_it = locks_.find(study_uid);
    if (lock_it == locks_.end()) {
        return kcenon::common::Result<std::monostate>::err(
            kcenon::common::error_info{
                lock_error::not_found,
                "Lock not found for study",
                "study_lock_manager"});
    }
 
    const auto duration = lock_it->second.info.duration();
    const auto type = lock_it->second.info.type;
    lock_info released_info = lock_it->second.info;
 
    // Remove token mapping
    auto token_it = token_to_study_.find(lock_it->second.info.token_id);
    if (token_it != token_to_study_.end()) {
        token_to_study_.erase(token_it);
    }
 
    // Remove all shared holder tokens
    for (const auto& shared_holder : lock_it->second.shared_holders) {
        // Shared holders may have separate tokens - clean up if needed
        (void)shared_holder;
    }
 
    locks_.erase(lock_it);
 
    {
        std::lock_guard stats_lock{stats_mutex_};
        ++stats_.force_unlock_count;
    }
    record_release(type, duration);
 
    if (on_lock_released_) {
        lock.unlock();
        on_lock_released_(study_uid, released_info);
    }
 
    return kcenon::common::Result<std::monostate>::ok(std::monostate{});
}

References kcenon::pacs::workflow::lock_error::not_found, and kcenon::pacs::workflow::lock_error::permission_denied.

generate_token_id()

auto kcenon::pacs::workflow::study_lock_manager::generate_token_id ( ) const -> std::string

nodiscardprivate

Generate a unique token ID.

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 787 of file study_lock_manager.cpp.

                                                              {
    const auto id = next_token_id_.fetch_add(1);
    const auto now = std::chrono::system_clock::now();
    const auto time_ms = std::chrono::duration_cast<std::chrono::milliseconds>(
        now.time_since_epoch()).count();
 
    std::ostringstream oss;
    oss << "lock_" << std::hex << std::setfill('0')
        << std::setw(12) << time_ms
        << "_" << std::setw(8) << id;
 
    return oss.str();
}

References next_token_id_.

get_all_locks()

auto kcenon::pacs::workflow::study_lock_manager::get_all_locks ( ) const -> std::vector<lock_info>

nodiscard

Get all currently held locks.

Returns

Vector of lock information for all held locks

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 613 of file study_lock_manager.cpp.

                                                                     {
    std::shared_lock lock{mutex_};
 
    std::vector<lock_info> result;
    result.reserve(locks_.size());
 
    for (const auto& [study_uid, entry] : locks_) {
        if (!entry.info.is_expired()) {
            result.push_back(entry.info);
        }
    }
 
    return result;
}

References lock(), locks_, and mutex_.

Here is the call graph for this function:

get_config()

auto kcenon::pacs::workflow::study_lock_manager::get_config ( ) const -> const study_lock_manager_config&

nodiscard

Get the current configuration.

Returns

Current configuration

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 757 of file study_lock_manager.cpp.

                                        {
    return config_;
}

References config_.

get_expired_locks()

auto kcenon::pacs::workflow::study_lock_manager::get_expired_locks ( ) const -> std::vector<lock_info>

nodiscard

Get all expired locks.

Returns

Vector of lock information for expired locks

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 669 of file study_lock_manager.cpp.

                                                                         {
    std::shared_lock lock{mutex_};
 
    std::vector<lock_info> result;
 
    for (const auto& [study_uid, entry] : locks_) {
        if (entry.info.is_expired()) {
            result.push_back(entry.info);
        }
    }
 
    return result;
}

References lock(), locks_, and mutex_.

Here is the call graph for this function:

get_lock_info()

auto kcenon::pacs::workflow::study_lock_manager::get_lock_info ( const std::string & study_uid ) const -> std::optional<lock_info>

nodiscard

Get lock information for a study.

Parameters

study_uid

Study UID to query

Returns

Lock information if locked, nullopt otherwise

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 506 of file study_lock_manager.cpp.

                              {
    std::shared_lock lock{mutex_};
 
    auto it = locks_.find(study_uid);
    if (it == locks_.end()) {
        return std::nullopt;
    }
 
    if (it->second.info.is_expired()) {
        return std::nullopt;
    }
 
    return it->second.info;
}

get_lock_info_by_token()

auto kcenon::pacs::workflow::study_lock_manager::get_lock_info_by_token ( const std::string & token_id ) const -> std::optional<lock_info>

nodiscard

Get lock information by token ID.

Parameters

token_id

Token ID to query

Returns

Lock information if found, nullopt otherwise

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 522 of file study_lock_manager.cpp.

                              {
    std::shared_lock lock{mutex_};
 
    auto token_it = token_to_study_.find(token_id);
    if (token_it == token_to_study_.end()) {
        return std::nullopt;
    }
 
    auto lock_it = locks_.find(token_it->second);
    if (lock_it == locks_.end()) {
        return std::nullopt;
    }
 
    if (lock_it->second.info.is_expired()) {
        return std::nullopt;
    }
 
    return lock_it->second.info;
}

get_locks_by_holder()

auto kcenon::pacs::workflow::study_lock_manager::get_locks_by_holder ( const std::string & holder ) const -> std::vector<lock_info>

nodiscard

Get all locks held by a specific holder.

Parameters

holder

Identifier of the lock holder

Returns

Vector of lock information for the holder's locks

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 628 of file study_lock_manager.cpp.

                            {
    const auto resolved_holder = resolve_holder(holder);
    std::shared_lock lock{mutex_};
 
    std::vector<lock_info> result;
 
    for (const auto& [study_uid, entry] : locks_) {
        if (entry.info.is_expired()) continue;
 
        if (entry.info.holder == resolved_holder) {
            result.push_back(entry.info);
        } else if (entry.info.type == lock_type::shared) {
            auto it = std::find(
                entry.shared_holders.begin(),
                entry.shared_holders.end(),
                resolved_holder);
            if (it != entry.shared_holders.end()) {
                result.push_back(entry.info);
            }
        }
    }
 
    return result;
}

References kcenon::pacs::workflow::shared.

get_locks_by_type()

auto kcenon::pacs::workflow::study_lock_manager::get_locks_by_type ( lock_type type ) const -> std::vector<lock_info>

nodiscard

Get all locks of a specific type.

Parameters

type	Lock type to filter by

Returns

Vector of lock information for matching locks

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 654 of file study_lock_manager.cpp.

                            {
    std::shared_lock lock{mutex_};
 
    std::vector<lock_info> result;
 
    for (const auto& [study_uid, entry] : locks_) {
        if (!entry.info.is_expired() && entry.info.type == type) {
            result.push_back(entry.info);
        }
    }
 
    return result;
}

get_stats()

auto kcenon::pacs::workflow::study_lock_manager::get_stats ( ) const -> lock_manager_stats

nodiscard

Get lock manager statistics.

Returns

Current statistics

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 722 of file study_lock_manager.cpp.

                                                               {
    std::lock_guard stats_lock{stats_mutex_};
    std::shared_lock lock{mutex_};
 
    lock_manager_stats current_stats = stats_;
    current_stats.active_locks = 0;
    current_stats.exclusive_locks = 0;
    current_stats.shared_locks = 0;
    current_stats.migration_locks = 0;
 
    for (const auto& [study_uid, entry] : locks_) {
        if (!entry.info.is_expired()) {
            ++current_stats.active_locks;
            switch (entry.info.type) {
                case lock_type::exclusive:
                    ++current_stats.exclusive_locks;
                    break;
                case lock_type::shared:
                    ++current_stats.shared_locks;
                    break;
                case lock_type::migration:
                    ++current_stats.migration_locks;
                    break;
            }
        }
    }
 
    return current_stats;
}

References kcenon::pacs::workflow::lock_manager_stats::active_locks, kcenon::pacs::workflow::exclusive, kcenon::pacs::workflow::lock_manager_stats::exclusive_locks, lock(), locks_, kcenon::pacs::workflow::migration, kcenon::pacs::workflow::lock_manager_stats::migration_locks, mutex_, kcenon::pacs::workflow::shared, kcenon::pacs::workflow::lock_manager_stats::shared_locks, stats_, and stats_mutex_.

Here is the call graph for this function:

is_locked() [1/2]

auto kcenon::pacs::workflow::study_lock_manager::is_locked ( const std::string & study_uid ) const -> bool

nodiscard

Check if a study is locked.

Parameters

study_uid

Study UID to check

Returns

true if the study is locked

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 473 of file study_lock_manager.cpp.

                                                                           {
    std::shared_lock lock{mutex_};
 
    auto it = locks_.find(study_uid);
    if (it == locks_.end()) {
        return false;
    }
 
    // Check if expired
    if (it->second.info.is_expired()) {
        return false;
    }
 
    return true;
}

is_locked() [2/2]

auto kcenon::pacs::workflow::study_lock_manager::is_locked ( const std::string & study_uid, lock_type type ) const -> bool

nodiscard

Check if a study has a specific lock type.

Parameters

study_uid	Study UID to check
type	Lock type to check for

Returns

true if the study has the specified lock type

Definition at line 489 of file study_lock_manager.cpp.

                                  {
    std::shared_lock lock{mutex_};
 
    auto it = locks_.find(study_uid);
    if (it == locks_.end()) {
        return false;
    }
 
    if (it->second.info.is_expired()) {
        return false;
    }
 
    return it->second.info.type == type;
}

lock() [1/2]

auto kcenon::pacs::workflow::study_lock_manager::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

Acquire an exclusive lock on a study.

Parameters

study_uid	Study UID to lock
reason	Reason for acquiring the lock
holder	Identifier of the lock holder (default: current thread)
timeout	Optional timeout for the lock (0 = use default)

Returns

Result containing lock_token or error

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 69 of file study_lock_manager.cpp.

                                                                {
    return lock(study_uid, lock_type::exclusive, reason, holder, timeout);
}

References kcenon::pacs::workflow::exclusive.

Referenced by get_all_locks(), get_expired_locks(), get_stats(), set_config(), and ~study_lock_manager().

Here is the caller graph for this function:

lock() [2/2]

auto kcenon::pacs::workflow::study_lock_manager::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

Acquire a lock of specific type on a study.

Parameters

study_uid	Study UID to lock
type	Type of lock to acquire
reason	Reason for acquiring the lock
holder	Identifier of the lock holder
timeout	Optional timeout for the lock

Returns

Result containing lock_token or error

Definition at line 77 of file study_lock_manager.cpp.

                                                                {
    const auto resolved_holder = resolve_holder(holder);
    const auto expiry = calculate_expiry(timeout);
    const auto now = std::chrono::system_clock::now();
 
    std::unique_lock lock{mutex_};
 
    // Check if lock can be acquired
    auto it = locks_.find(study_uid);
    if (it != locks_.end()) {
        auto& existing = it->second;
 
        // Check if existing lock is expired
        if (existing.info.is_expired()) {
            // Clean up expired lock
            auto token_it = token_to_study_.find(existing.info.token_id);
            if (token_it != token_to_study_.end()) {
                token_to_study_.erase(token_it);
            }
            locks_.erase(it);
            it = locks_.end();
 
            // Notify expiration
            if (on_lock_expired_) {
                lock.unlock();
                on_lock_expired_(study_uid, existing.info);
                lock.lock();
            }
        }
    }
 
    // Re-check after potential cleanup
    it = locks_.find(study_uid);
    if (it != locks_.end()) {
        auto& existing = it->second;
 
        // Handle shared lock upgrade/coexistence
        if (type == lock_type::shared &&
            existing.info.type == lock_type::shared) {
            // Check max shared locks
            if (existing.shared_holders.size() >= config_.max_shared_locks) {
                return kcenon::common::Result<lock_token>::err(
                    kcenon::common::error_info{
                        lock_error::max_shared_exceeded,
                        "Maximum shared locks exceeded",
                        "study_lock_manager"});
            }
 
            // Add holder to shared list
            existing.shared_holders.push_back(resolved_holder);
            existing.info.shared_count = existing.shared_holders.size();
 
            // Generate new token for this shared holder
            const auto token_id = generate_token_id();
            token_to_study_[token_id] = study_uid;
 
            lock_token token;
            token.token_id = token_id;
            token.study_uid = study_uid;
            token.type = lock_type::shared;
            token.acquired_at = now;
            token.expires_at = expiry;
 
            record_acquisition(type);
 
            if (on_lock_acquired_) {
                lock_info info = existing.info;
                info.token_id = token_id;
                info.holder = resolved_holder;
                lock.unlock();
                on_lock_acquired_(study_uid, info);
            }
 
            return kcenon::common::Result<lock_token>::ok(token);
        }
 
        // Cannot acquire lock - already locked
        {
            std::lock_guard stats_lock{stats_mutex_};
            ++stats_.contention_count;
        }
 
        return kcenon::common::Result<lock_token>::err(
            kcenon::common::error_info{
                lock_error::already_locked,
                "Study is already locked by: " + existing.info.holder,
                "study_lock_manager",
                "Lock type: " + to_string(existing.info.type)});
    }
 
    // Create new lock
    const auto token_id = generate_token_id();
 
    lock_entry entry;
    entry.info.study_uid = study_uid;
    entry.info.type = type;
    entry.info.reason = reason;
    entry.info.holder = resolved_holder;
    entry.info.token_id = token_id;
    entry.info.acquired_at = now;
    entry.info.expires_at = expiry;
    entry.info.shared_count = (type == lock_type::shared) ? 1 : 0;
 
    if (type == lock_type::shared) {
        entry.shared_holders.push_back(resolved_holder);
    }
 
    locks_[study_uid] = std::move(entry);
    token_to_study_[token_id] = study_uid;
 
    lock_token token;
    token.token_id = token_id;
    token.study_uid = study_uid;
    token.type = type;
    token.acquired_at = now;
    token.expires_at = expiry;
 
    record_acquisition(type);
 
    if (on_lock_acquired_) {
        lock_info info = locks_[study_uid].info;
        lock.unlock();
        on_lock_acquired_(study_uid, info);
    }
 
    return kcenon::common::Result<lock_token>::ok(token);
}

References kcenon::pacs::workflow::lock_info::acquired_at, kcenon::pacs::workflow::lock_token::acquired_at, kcenon::pacs::workflow::lock_error::already_locked, kcenon::pacs::workflow::lock_info::expires_at, kcenon::pacs::workflow::lock_token::expires_at, kcenon::pacs::workflow::lock_info::holder, kcenon::pacs::workflow::study_lock_manager::lock_entry::info, kcenon::pacs::workflow::lock_error::max_shared_exceeded, kcenon::pacs::workflow::lock_info::reason, kcenon::pacs::workflow::shared, kcenon::pacs::workflow::lock_info::shared_count, kcenon::pacs::workflow::study_lock_manager::lock_entry::shared_holders, kcenon::pacs::workflow::lock_info::study_uid, kcenon::pacs::workflow::lock_token::study_uid, kcenon::pacs::workflow::to_string(), kcenon::pacs::workflow::lock_info::token_id, kcenon::pacs::workflow::lock_token::token_id, kcenon::pacs::workflow::lock_info::type, and kcenon::pacs::workflow::lock_token::type.

Here is the call graph for this function:

operator=() [1/2]

study_lock_manager & kcenon::pacs::workflow::study_lock_manager::operator= ( const study_lock_manager & )

delete

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

operator=() [2/2]

study_lock_manager & kcenon::pacs::workflow::study_lock_manager::operator= ( study_lock_manager && other )

noexcept

Definition at line 49 of file study_lock_manager.cpp.

                                         {
    if (this != &other) {
        std::unique_lock lock{mutex_};
        config_ = std::move(other.config_);
        locks_ = std::move(other.locks_);
        token_to_study_ = std::move(other.token_to_study_);
        stats_ = std::move(other.stats_);
        next_token_id_.store(other.next_token_id_.load());
        on_lock_acquired_ = std::move(other.on_lock_acquired_);
        on_lock_released_ = std::move(other.on_lock_released_);
        on_lock_expired_ = std::move(other.on_lock_expired_);
    }
    return *this;
}

record_acquisition()

void kcenon::pacs::workflow::study_lock_manager::record_acquisition ( lock_type type )

private

Update statistics on lock acquisition.

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 844 of file study_lock_manager.cpp.

                                                          {
    std::lock_guard stats_lock{stats_mutex_};
    ++stats_.total_acquisitions;
    (void)type;  // Type-specific stats are calculated in get_stats()
}

References stats_, stats_mutex_, and kcenon::pacs::workflow::lock_manager_stats::total_acquisitions.

record_release()

void kcenon::pacs::workflow::study_lock_manager::record_release ( lock_type type, std::chrono::milliseconds duration )

private

Update statistics on lock release.

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 850 of file study_lock_manager.cpp.

                                    {
    std::lock_guard stats_lock{stats_mutex_};
    ++stats_.total_releases;
 
    // Update average duration
    if (stats_.total_releases > 0) {
        auto total_duration =
            stats_.avg_lock_duration.count() * (stats_.total_releases - 1) +
            duration.count();
        stats_.avg_lock_duration =
            std::chrono::milliseconds{total_duration / stats_.total_releases};
    }
 
    // Update max duration
    if (duration > stats_.max_lock_duration) {
        stats_.max_lock_duration = duration;
    }
 
    (void)type;  // Type-specific stats are calculated in get_stats()
}

References kcenon::pacs::workflow::lock_manager_stats::avg_lock_duration, kcenon::pacs::workflow::lock_manager_stats::max_lock_duration, stats_, stats_mutex_, and kcenon::pacs::workflow::lock_manager_stats::total_releases.

refresh_lock()

auto kcenon::pacs::workflow::study_lock_manager::refresh_lock ( const lock_token & token, std::chrono::seconds extension = std::chrono::seconds{0} ) -> kcenon::common::Result<lock_token>

nodiscard

Refresh a lock (extend its timeout)

Parameters

token	Lock token to refresh
extension	Additional time to extend the lock

Returns

Result containing updated lock_token or error

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 564 of file study_lock_manager.cpp.

                                      {
    std::unique_lock lock{mutex_};
 
    auto token_it = token_to_study_.find(token.token_id);
    if (token_it == token_to_study_.end()) {
        return kcenon::common::Result<lock_token>::err(
            kcenon::common::error_info{
                lock_error::invalid_token,
                "Invalid or expired token",
                "study_lock_manager"});
    }
 
    auto lock_it = locks_.find(token_it->second);
    if (lock_it == locks_.end()) {
        return kcenon::common::Result<lock_token>::err(
            kcenon::common::error_info{
                lock_error::not_found,
                "Lock not found",
                "study_lock_manager"});
    }
 
    if (lock_it->second.info.is_expired()) {
        return kcenon::common::Result<lock_token>::err(
            kcenon::common::error_info{
                lock_error::expired,
                "Lock has expired",
                "study_lock_manager"});
    }
 
    // Calculate new expiry
    auto new_extension = extension.count() > 0 ? extension : config_.default_timeout;
    if (new_extension.count() > 0) {
        lock_it->second.info.expires_at =
            std::chrono::system_clock::now() + new_extension;
    }
 
    lock_token updated_token = token;
    updated_token.expires_at = lock_it->second.info.expires_at;
 
    return kcenon::common::Result<lock_token>::ok(updated_token);
}

References kcenon::pacs::workflow::lock_error::expired, kcenon::pacs::workflow::lock_token::expires_at, kcenon::pacs::workflow::lock_error::invalid_token, and kcenon::pacs::workflow::lock_error::not_found.

reset_stats()

void kcenon::pacs::workflow::study_lock_manager::reset_stats

(

)

Reset statistics counters.

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 752 of file study_lock_manager.cpp.

                                     {
    std::lock_guard stats_lock{stats_mutex_};
    stats_ = lock_manager_stats{};
}

References stats_, and stats_mutex_.

resolve_holder()

auto kcenon::pacs::workflow::study_lock_manager::resolve_holder ( const std::string & holder ) const -> std::string

nodiscardprivate

Get holder identifier (uses thread ID if empty)

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 801 of file study_lock_manager.cpp.

                 {
    if (!holder.empty()) {
        return holder;
    }
 
    // Use thread ID as default holder
    std::ostringstream oss;
    oss << "thread_" << std::this_thread::get_id();
    return oss.str();
}

set_config()

void kcenon::pacs::workflow::study_lock_manager::set_config

(

const study_lock_manager_config &

config

)

Update configuration.

Note: Changes to some settings may not take effect immediately.

Parameters

config

New configuration

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 762 of file study_lock_manager.cpp.

                                                                           {
    std::unique_lock lock{mutex_};
    config_ = config;
}

References config_, lock(), and mutex_.

Here is the call graph for this function:

set_on_lock_acquired()

void kcenon::pacs::workflow::study_lock_manager::set_on_lock_acquired

(

lock_event_callback

callback

)

Set callback for lock acquisition events.

Parameters

callback

Callback function

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 771 of file study_lock_manager.cpp.

                                                                          {
    on_lock_acquired_ = std::move(callback);
}

References on_lock_acquired_.

set_on_lock_expired()

void kcenon::pacs::workflow::study_lock_manager::set_on_lock_expired

(

lock_event_callback

callback

)

Set callback for lock expiration events.

Parameters

callback

Callback function

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 779 of file study_lock_manager.cpp.

                                                                         {
    on_lock_expired_ = std::move(callback);
}

References on_lock_expired_.

set_on_lock_released()

void kcenon::pacs::workflow::study_lock_manager::set_on_lock_released

(

lock_event_callback

callback

)

Set callback for lock release events.

Parameters

callback

Callback function

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 775 of file study_lock_manager.cpp.

                                                                          {
    on_lock_released_ = std::move(callback);
}

References on_lock_released_.

try_lock()

auto kcenon::pacs::workflow::study_lock_manager::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>

nodiscard

Try to acquire a lock without blocking.

Parameters

study_uid	Study UID to lock
type	Type of lock to acquire
reason	Reason for acquiring the lock
holder	Identifier of the lock holder
timeout	Optional timeout for the lock

Returns

Result containing lock_token or error if lock unavailable

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 210 of file study_lock_manager.cpp.

                                                                {
    // try_lock is the same as lock for this implementation
    // since we don't block waiting
    return lock(study_uid, type, reason, holder, timeout);
}

unlock() [1/2]

auto kcenon::pacs::workflow::study_lock_manager::unlock ( const lock_token & token ) -> kcenon::common::Result<std::monostate>

nodiscard

Release a lock using its token.

Parameters

token

Lock token received from lock()

Returns

Result indicating success or error

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 225 of file study_lock_manager.cpp.

                                        {
    std::unique_lock lock{mutex_};
 
    // Find study by token
    auto token_it = token_to_study_.find(token.token_id);
    if (token_it == token_to_study_.end()) {
        return kcenon::common::Result<std::monostate>::err(
            kcenon::common::error_info{
                lock_error::invalid_token,
                "Invalid or expired token",
                "study_lock_manager"});
    }
 
    const auto study_uid = token_it->second;
    auto lock_it = locks_.find(study_uid);
    if (lock_it == locks_.end()) {
        // Token exists but lock doesn't - clean up
        token_to_study_.erase(token_it);
        return kcenon::common::Result<std::monostate>::err(
            kcenon::common::error_info{
                lock_error::not_found,
                "Lock not found",
                "study_lock_manager"});
    }
 
    auto& entry = lock_it->second;
    const auto duration = entry.info.duration();
    const auto type = entry.info.type;
    lock_info released_info = entry.info;
 
    // Handle shared lock release
    if (type == lock_type::shared && entry.shared_holders.size() > 1) {
        // Just remove this holder from shared list
        auto holder_it = std::find(
            entry.shared_holders.begin(),
            entry.shared_holders.end(),
            token.token_id);  // Using token_id as holder identifier for shared
 
        if (holder_it != entry.shared_holders.end()) {
            entry.shared_holders.erase(holder_it);
        }
        token_to_study_.erase(token_it);
        entry.info.shared_count = entry.shared_holders.size();
 
        record_release(type, duration);
 
        if (on_lock_released_) {
            lock.unlock();
            on_lock_released_(study_uid, released_info);
        }
 
        return kcenon::common::Result<std::monostate>::ok(std::monostate{});
    }
 
    // Remove lock entirely
    token_to_study_.erase(token_it);
    locks_.erase(lock_it);
 
    record_release(type, duration);
 
    if (on_lock_released_) {
        lock.unlock();
        on_lock_released_(study_uid, released_info);
    }
 
    return kcenon::common::Result<std::monostate>::ok(std::monostate{});
}

References kcenon::pacs::workflow::lock_error::invalid_token, kcenon::pacs::workflow::lock_error::not_found, and kcenon::pacs::workflow::shared.

unlock() [2/2]

auto kcenon::pacs::workflow::study_lock_manager::unlock ( const std::string & study_uid, const std::string & holder ) -> kcenon::common::Result<std::monostate>

nodiscard

Release a lock by study UID and holder.

Parameters

study_uid	Study UID to unlock
holder	Identifier of the lock holder

Returns

Result indicating success or error

Definition at line 294 of file study_lock_manager.cpp.

                                        {
    const auto resolved_holder = resolve_holder(holder);
 
    std::unique_lock lock{mutex_};
 
    auto lock_it = locks_.find(study_uid);
    if (lock_it == locks_.end()) {
        return kcenon::common::Result<std::monostate>::err(
            kcenon::common::error_info{
                lock_error::not_found,
                "Lock not found for study",
                "study_lock_manager"});
    }
 
    auto& entry = lock_it->second;
 
    // Verify holder matches
    if (entry.info.holder != resolved_holder) {
        // Check shared holders
        bool found_shared = false;
        if (entry.info.type == lock_type::shared) {
            auto holder_it = std::find(
                entry.shared_holders.begin(),
                entry.shared_holders.end(),
                resolved_holder);
            if (holder_it != entry.shared_holders.end()) {
                found_shared = true;
                entry.shared_holders.erase(holder_it);
                entry.info.shared_count = entry.shared_holders.size();
            }
        }
 
        if (!found_shared) {
            return kcenon::common::Result<std::monostate>::err(
                kcenon::common::error_info{
                    lock_error::permission_denied,
                    "Lock held by different holder: " + entry.info.holder,
                    "study_lock_manager"});
        }
 
        if (!entry.shared_holders.empty()) {
            // Other shared holders remain
            record_release(entry.info.type, entry.info.duration());
            return kcenon::common::Result<std::monostate>::ok(std::monostate{});
        }
    }
 
    const auto duration = entry.info.duration();
    const auto type = entry.info.type;
    lock_info released_info = entry.info;
 
    // Remove token mapping
    auto token_it = token_to_study_.find(entry.info.token_id);
    if (token_it != token_to_study_.end()) {
        token_to_study_.erase(token_it);
    }
 
    locks_.erase(lock_it);
 
    record_release(type, duration);
 
    if (on_lock_released_) {
        lock.unlock();
        on_lock_released_(study_uid, released_info);
    }
 
    return kcenon::common::Result<std::monostate>::ok(std::monostate{});
}

References kcenon::pacs::workflow::lock_error::not_found, kcenon::pacs::workflow::lock_error::permission_denied, and kcenon::pacs::workflow::shared.

unlock_all_by_holder()

auto kcenon::pacs::workflow::study_lock_manager::unlock_all_by_holder

(

const std::string &

holder

)

-> std::size_t

Release all locks held by a specific holder.

Parameters

holder

Identifier of the lock holder

Returns

Number of locks released

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 422 of file study_lock_manager.cpp.

                 {
    const auto resolved_holder = resolve_holder(holder);
    std::size_t count = 0;
 
    std::unique_lock lock{mutex_};
 
    std::vector<std::string> to_remove;
    for (auto& [study_uid, entry] : locks_) {
        if (entry.info.holder == resolved_holder) {
            to_remove.push_back(study_uid);
        } else if (entry.info.type == lock_type::shared) {
            // Check shared holders
            auto it = std::find(
                entry.shared_holders.begin(),
                entry.shared_holders.end(),
                resolved_holder);
            if (it != entry.shared_holders.end()) {
                entry.shared_holders.erase(it);
                entry.info.shared_count = entry.shared_holders.size();
                ++count;
 
                if (entry.shared_holders.empty()) {
                    to_remove.push_back(study_uid);
                }
            }
        }
    }
 
    for (const auto& study_uid : to_remove) {
        auto it = locks_.find(study_uid);
        if (it != locks_.end()) {
            // Remove token mapping
            auto token_it = token_to_study_.find(it->second.info.token_id);
            if (token_it != token_to_study_.end()) {
                token_to_study_.erase(token_it);
            }
 
            record_release(it->second.info.type, it->second.info.duration());
            locks_.erase(it);
            ++count;
        }
    }
 
    return count;
}

References kcenon::pacs::workflow::shared.

validate_token()

auto kcenon::pacs::workflow::study_lock_manager::validate_token ( const lock_token & token ) const -> bool

nodiscard

Validate a lock token.

Parameters

token

Lock token to validate

Returns

true if the token is valid and the lock is still held

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 544 of file study_lock_manager.cpp.

                                                                             {
    std::shared_lock lock{mutex_};
 
    auto token_it = token_to_study_.find(token.token_id);
    if (token_it == token_to_study_.end()) {
        return false;
    }
 
    auto lock_it = locks_.find(token_it->second);
    if (lock_it == locks_.end()) {
        return false;
    }
 
    if (lock_it->second.info.is_expired()) {
        return false;
    }
 
    return token_it->second == token.study_uid;
}

Member Data Documentation

config_

study_lock_manager_config kcenon::pacs::workflow::study_lock_manager::config_

private

Configuration.

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 688 of file study_lock_manager.h.

Referenced by get_config(), and set_config().

locks_

std::map<std::string, lock_entry> kcenon::pacs::workflow::study_lock_manager::locks_

private

Lock entries (study_uid -> lock_entry)

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 691 of file study_lock_manager.h.

Referenced by get_all_locks(), get_expired_locks(), get_stats(), and ~study_lock_manager().

mutex_

std::shared_mutex kcenon::pacs::workflow::study_lock_manager::mutex_

mutableprivate

Mutex for thread-safe access.

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 697 of file study_lock_manager.h.

Referenced by get_all_locks(), get_expired_locks(), get_stats(), set_config(), and ~study_lock_manager().

next_token_id_

std::atomic<uint64_t> kcenon::pacs::workflow::study_lock_manager::next_token_id_ {1}

mutableprivate

Next token ID counter.

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 706 of file study_lock_manager.h.

{1};

Referenced by generate_token_id().

on_lock_acquired_

lock_event_callback kcenon::pacs::workflow::study_lock_manager::on_lock_acquired_

private

Event callbacks.

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 709 of file study_lock_manager.h.

Referenced by set_on_lock_acquired().

on_lock_expired_

lock_event_callback kcenon::pacs::workflow::study_lock_manager::on_lock_expired_

private

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 711 of file study_lock_manager.h.

Referenced by set_on_lock_expired().

on_lock_released_

lock_event_callback kcenon::pacs::workflow::study_lock_manager::on_lock_released_

private

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 710 of file study_lock_manager.h.

Referenced by set_on_lock_released().

stats_

lock_manager_stats kcenon::pacs::workflow::study_lock_manager::stats_

mutableprivate

Statistics.

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 700 of file study_lock_manager.h.

Referenced by get_stats(), record_acquisition(), record_release(), and reset_stats().

stats_mutex_

std::mutex kcenon::pacs::workflow::study_lock_manager::stats_mutex_

mutableprivate

Mutex for statistics.

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 703 of file study_lock_manager.h.

Referenced by get_stats(), record_acquisition(), record_release(), and reset_stats().

token_to_study_

std::map<std::string, std::string> kcenon::pacs::workflow::study_lock_manager::token_to_study_

private

Token to study UID mapping for fast lookup.

Examples

/home/runner/work/pacs_system/pacs_system/include/kcenon/pacs/workflow/study_lock_manager.h.

Definition at line 694 of file study_lock_manager.h.

Referenced by ~study_lock_manager().

---

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

• include/kcenon/pacs/workflow/study_lock_manager.h
• src/workflow/study_lock_manager.cpp