aimx/aim/

lock_manager.rs

//! Workflow Lock Manager for Concurrent Access Control
//!
//! This module provides a thread-safe lock manager for controlling concurrent access
//! to AIM workflows. It uses fine-grained locking to allow maximum concurrency while
//! ensuring data consistency during write operations.
//!
//! # Overview
//!
//! The lock manager implements a per-workflow locking strategy that:
//! - Allows unlimited concurrent read access to workflows
//! - Ensures exclusive write access to individual workflows
//! - Uses reference-based locking to prevent conflicts
//! - Provides a global singleton instance for application-wide coordination
//!
//! # Concurrency Model
//!
//! AIM uses a Multi-Version Concurrency Control (MVCC) model where:
//! - Readers access consistent snapshots without blocking
//! - Writers acquire exclusive locks on specific workflows
//! - Locks are automatically released when guard objects are dropped
//! - Fine-grained locking minimizes contention compared to global locks
//!
//! # Examples
//!
//! ```rust
//! use aimx::aim::get_lock_manager;
//! use aimx::Reference;
//!
//! // Get the global lock manager instance
//! let lock_manager = get_lock_manager();
//!
//! // Acquire a lock for a specific workflow
//! let reference = Reference::One("my_workflow".to_string());
//! let lock_guard = lock_manager.acquire_workflow_lock(reference);
//!
//! // The lock is held until `lock_guard` is dropped
//! // Perform write operations on the workflow...
//!
//! // Lock is automatically released when `lock_guard` goes out of scope
//! ```
//!
//! # Thread Safety
//!
//! The `LockManager` is designed to be used as a global singleton and is
//! completely thread-safe. All operations use atomic reference counting
//! and concurrent data structures to ensure safe access from multiple threads.
//!
//! # Implementation Details
//!
//! - Uses `DashMap` for lock-free concurrent access to the lock table
//! - Employs `Arc<Mutex<()>>` for shared ownership of individual locks
//! - Provides lazy initialization of locks on first access
//! - Future enhancements may include file system-level locking mechanisms

use dashmap::DashMap;
use once_cell::sync::Lazy;
use std::sync::{Arc, Mutex};
use crate::Reference;

/// Manages concurrent access to workflows through fine-grained locking
///
/// The `LockManager` maintains a mapping of workflow references to mutex guards,
/// allowing for per-workflow exclusive access control. This approach maximizes
/// concurrency by only blocking access to the specific workflow being modified,
/// rather than using a global lock that would block all workflow operations.
///
/// # Design Principles
///
/// - **Fine-grained locking**: Each workflow has its own lock
/// - **Lazy initialization**: Locks are created on first access
/// - **Shared ownership**: Multiple references to the same lock using `Arc`
/// - **Automatic cleanup**: Locks are managed by the `DashMap` and cleaned up automatically
///
/// # Thread Safety
///
/// This struct is completely thread-safe and can be safely accessed from
/// multiple threads. The `Default` implementation is used to create the
/// global singleton instance.
#[derive(Debug, Default)]
pub struct LockManager {
    /// Maps workflow references to their corresponding mutex guards
    ///
    /// Uses `DashMap` for lock-free concurrent access. The value is an `Arc<Mutex<()>>`
    /// which allows multiple owners of the same lock while ensuring mutual exclusion
    /// when the mutex is locked.
    workflow_locks: DashMap<Reference, Arc<Mutex<()>>>,
}

impl LockManager {
    /// Creates a new `LockManager` instance
    ///
    /// Returns a new lock manager with an empty lock table. Locks will be
    /// created lazily as workflows are accessed.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::aim::LockManager;
    ///
    /// let lock_manager = LockManager::new();
    /// ```
    pub fn new() -> Self {
        Self::default()
    }

    /// Acquires an exclusive write lock for a single workflow by reference
    ///
    /// This method retrieves or creates a mutex for the specified workflow reference
    /// and returns a clone of the `Arc<Mutex<()>>`. The caller must call `lock()`
    /// on this mutex to actually acquire the exclusive lock.
    ///
    /// # Important Notes
    ///
    /// - The lock is not acquired by this method - it only provides access to the mutex
    /// - Multiple calls with the same reference return the same mutex
    /// - The lock is released when the `MutexGuard` is dropped
    /// - For production use, ensure the reference is canonicalized to prevent lock aliasing
    ///
    /// # Parameters
    ///
    /// * `reference` - The workflow reference to lock
    ///
    /// # Returns
    ///
    /// An `Arc<Mutex<()>>` that can be used to acquire the exclusive lock
    ///
    /// # Examples
    ///
    /// ```rust
    /// use aimx::aim::LockManager;
    /// use aimx::Reference;
    /// use std::sync::Arc;
    ///
    /// let lock_manager = LockManager::new();
    /// let reference = Reference::One("my_workflow".to_string());
    ///
    /// // Get the mutex for this workflow
    /// let mutex = lock_manager.acquire_workflow_lock(reference);
    ///
    /// // Actually acquire the lock
    /// let _guard = mutex.lock().unwrap();
    ///
    /// // Perform exclusive operations...
    /// // Lock is released when `_guard` is dropped
    /// ```
    ///
    /// NOTE: I plan to probably add an fs lock mechanism to this at some point in the future.
    pub fn acquire_workflow_lock(&self, reference: Reference) -> Arc<Mutex<()>> {
        // In a real app, ensure `target_file` is canonicalized before use
        // to prevent lock aliasing issues (e.g., `.` vs `foo/../.`).
        self.workflow_locks
            .entry(reference)
            .or_insert_with(|| Arc::new(Mutex::new(())))
            .clone()
    }
}

/// Global singleton instance of the `LockManager`
///
/// Uses lazy initialization to create the lock manager on first access.
/// This ensures the lock manager is only created when needed while providing
/// a globally accessible instance for the entire application.
static GLOBAL_LOCK_MANAGER: Lazy<LockManager> = Lazy::new(LockManager::new);

/// Returns the global singleton instance of the `LockManager`
///
/// This function provides access to the application-wide lock manager that
/// coordinates concurrent access to workflows. It uses lazy initialization
/// to create the manager on first access.
///
/// # Returns
///
/// A static reference to the global `LockManager` instance
///
/// # Examples
///
/// ```rust
/// use aimx::aim::get_lock_manager;
///
/// let lock_manager = get_lock_manager();
/// // Use the lock manager for workflow coordination
/// ```
pub fn get_lock_manager() -> &'static LockManager {
    &GLOBAL_LOCK_MANAGER
}