pmat 3.11.0

#![cfg_attr(coverage_nightly, coverage(off))]
//! Cache Strategy Orchestrator for PMAT
//!
//! This module provides a unified orchestrator that manages multiple caching strategies
//! and automatically selects the optimal strategy based on workload characteristics,
//! access patterns, and performance requirements.
//!
//! # Architecture
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────────┐
//! │                  Cache Strategy Orchestrator                    │
//! ├─────────────────────────────────────────────────────────────────┤
//! │  Workload Analyzer  │  Strategy Router  │  Performance Monitor  │
//! ├─────────────────────┼───────────────────┼───────────────────────┤
//! │   Adaptive Cache    │   Multi-Tier      │    Predictive Cache   │
//! │   LRU/LFU/TTL      │   L1/L2/L3        │    ML Predictions     │
//! └─────────────────────┴───────────────────┴───────────────────────┘
//! ```
//!
//! # Features
//!
//! - **Dynamic Strategy Selection**: Chooses optimal caching strategy per workload
//! - **Performance Monitoring**: Real-time cache effectiveness measurement
//! - **Adaptive Optimization**: Continuously improves based on usage patterns
//! - **Resource Management**: Intelligent memory and storage allocation
//! - **Fault Tolerance**: Graceful degradation and recovery

use crate::services::cache::advanced_strategies::{CacheTier, EvictionPolicy};
use anyhow::Result;
use parking_lot::RwLock;
use rustc_hash::FxHashMap;
use serde::{Deserialize, Serialize};
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::{Duration, Instant};
use tracing::{debug, info, warn};

/// Workload characteristics that influence cache strategy selection
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct WorkloadProfile {
    /// Average request rate (requests/second)
    pub request_rate: f64,
    /// Working set size (bytes)
    pub working_set_size: u64,
    /// Temporal locality factor (0.0-1.0)
    pub temporal_locality: f64,
    /// Spatial locality factor (0.0-1.0)
    pub spatial_locality: f64,
    /// Read/write ratio
    pub read_write_ratio: f64,
    /// Cache hit rate target
    pub target_hit_rate: f64,
    /// Latency sensitivity (0.0-1.0)
    pub latency_sensitivity: f64,
}

/// Cache strategy recommendation from the orchestrator
#[derive(Debug, Clone)]
pub struct StrategyRecommendation {
    /// Recommended eviction policy
    pub eviction_policy: EvictionPolicy,
    /// Recommended tier configuration
    pub tier_config: TierConfiguration,
    /// Expected performance improvement
    pub expected_improvement: f64,
    /// Confidence in recommendation (0.0-1.0)
    pub confidence: f64,
}

/// Configuration for cache tiers
#[derive(Debug, Clone)]
pub struct TierConfiguration {
    /// Memory allocation per tier (bytes)
    pub tier_allocations: FxHashMap<CacheTier, u64>,
    /// Enable/disable specific tiers
    pub enabled_tiers: FxHashMap<CacheTier, bool>,
    /// Inter-tier promotion thresholds
    pub promotion_thresholds: FxHashMap<CacheTier, f64>,
}

/// Performance metrics for strategy evaluation
#[derive(Debug, Clone, Default)]
pub struct PerformanceMetrics {
    /// Current hit rate
    pub hit_rate: f64,
    /// Average latency
    pub avg_latency: Duration,
    /// Memory utilization
    pub memory_utilization: f64,
    /// Throughput (operations/second)
    pub throughput: f64,
    /// Cache effectiveness score
    pub effectiveness_score: f64,
}

/// Cache strategy orchestrator
pub struct CacheOrchestrator {
    /// Current workload profile
    workload_profile: RwLock<WorkloadProfile>,
    /// Active cache strategies
    strategies: RwLock<FxHashMap<String, Box<dyn CacheStrategy + Send + Sync>>>,
    /// Performance monitoring
    metrics: RwLock<PerformanceMetrics>,
    /// Strategy evaluation history
    evaluation_history: RwLock<Vec<StrategyEvaluation>>,
    /// Configuration
    config: OrchestratorConfig,
    /// Performance counters
    counters: PerformanceCounters,
}

/// Configuration for the cache orchestrator
#[derive(Debug, Clone)]
pub struct OrchestratorConfig {
    /// Enable automatic strategy switching
    pub auto_strategy_switching: bool,
    /// Performance evaluation interval
    pub evaluation_interval: Duration,
    /// Minimum improvement threshold for strategy switch
    pub min_improvement_threshold: f64,
    /// Strategy evaluation window size
    pub evaluation_window: usize,
    /// Enable performance prediction
    pub enable_prediction: bool,
}

/// Historical strategy evaluation
#[derive(Debug, Clone)]
#[allow(dead_code)]
struct StrategyEvaluation {
    /// Performance achieved
    performance: PerformanceMetrics,
    /// Evaluation timestamp
    timestamp: Instant,
}

#[cfg(test)]
impl StrategyEvaluation {
    pub(crate) fn score(&self) -> f64 {
        self.performance.hit_rate * self.performance.throughput
    }

    pub(crate) fn is_valid(&self) -> bool {
        self.timestamp.elapsed().as_secs() < 3600
    }
}

/// Performance counters
#[derive(Debug)]
struct PerformanceCounters {
    strategy_switches: AtomicU64,
    evaluations_performed: AtomicU64,
    recommendations_generated: AtomicU64,
    performance_improvements: AtomicU64,
}

/// Trait for pluggable cache strategies (simplified for dynamic dispatch)
pub trait CacheStrategy {
    /// Get strategy identifier
    fn strategy_id(&self) -> &str;

    /// Get cache statistics
    fn get_stats(&self) -> PerformanceMetrics;
}

/// Configuration for individual cache strategies
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StrategyConfig {
    /// Strategy-specific parameters
    pub parameters: FxHashMap<String, serde_json::Value>,
    /// Resource limits
    pub resource_limits: ResourceLimits,
}

/// Resource limits for cache strategies
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ResourceLimits {
    /// Maximum memory usage (bytes)
    pub max_memory: u64,
    /// Maximum disk usage (bytes)
    pub max_disk: u64,
    /// Maximum CPU usage (percentage)
    pub max_cpu: f64,
}

// --- Extracted implementation and test files ---

include!("orchestrator_impls.rs");
include!("orchestrator_analysis.rs");
include!("orchestrator_tests.rs");