scirs2_core/profiling/

memory_profiling.rs

//! # Advanced Memory Profiling for SciRS2 v0.2.0
//!
//! This module provides comprehensive memory profiling capabilities using jemalloc.
//! It enables heap profiling, memory leak detection, and allocation pattern analysis.
//!
//! # Features
//!
//! - **Heap Profiling**: Track memory allocations and deallocations
//! - **Leak Detection**: Identify memory leaks
//! - **Allocation Patterns**: Analyze allocation patterns
//! - **Statistics**: Detailed memory statistics
//! - **Zero Overhead**: Disabled by default, minimal overhead when enabled
//!
//! # Example
//!
//! ```rust,no_run
//! use scirs2_core::profiling::memory_profiling::{MemoryProfiler, enable_profiling};
//!
//! // Enable memory profiling
//! enable_profiling().expect("Failed to enable profiling");
//!
//! // ... perform allocations ...
//!
//! // Get memory statistics
//! let stats = MemoryProfiler::get_stats().expect("Failed to get stats");
//! println!("Allocated: {} bytes", stats.allocated);
//! println!("Resident: {} bytes", stats.resident);
//! ```

#[cfg(feature = "profiling_memory")]
use crate::CoreResult;
#[cfg(feature = "profiling_memory")]
use std::collections::HashMap;
#[cfg(feature = "profiling_memory")]
use tikv_jemalloc_ctl::{epoch, stats};

/// Memory statistics from jemalloc
#[cfg(feature = "profiling_memory")]
#[derive(Debug, Clone)]
pub struct MemoryStats {
    /// Total allocated memory (bytes)
    pub allocated: usize,
    /// Resident memory (bytes)
    pub resident: usize,
    /// Mapped memory (bytes)
    pub mapped: usize,
    /// Metadata memory (bytes)
    pub metadata: usize,
    /// Retained memory (bytes)
    pub retained: usize,
}

#[cfg(feature = "profiling_memory")]
impl MemoryStats {
    /// Get current memory statistics
    pub fn current() -> CoreResult<Self> {
        // Update the epoch to get fresh statistics
        epoch::mib()
            .map_err(|e| {
                crate::CoreError::ConfigError(crate::error::ErrorContext::new(format!(
                    "Failed to get epoch: {}",
                    e
                )))
            })?
            .advance()
            .map_err(|e| {
                crate::CoreError::ConfigError(crate::error::ErrorContext::new(format!(
                    "Failed to advance epoch: {}",
                    e
                )))
            })?;

        let allocated = stats::allocated::mib()
            .map_err(|e| {
                crate::CoreError::ConfigError(crate::error::ErrorContext::new(format!(
                    "Failed to get allocated: {}",
                    e
                )))
            })?
            .read()
            .map_err(|e| {
                crate::CoreError::ConfigError(crate::error::ErrorContext::new(format!(
                    "Failed to read allocated: {}",
                    e
                )))
            })?;

        let resident = stats::resident::mib()
            .map_err(|e| {
                crate::CoreError::ConfigError(crate::error::ErrorContext::new(format!(
                    "Failed to get resident: {}",
                    e
                )))
            })?
            .read()
            .map_err(|e| {
                crate::CoreError::ConfigError(crate::error::ErrorContext::new(format!(
                    "Failed to read resident: {}",
                    e
                )))
            })?;

        let mapped = stats::mapped::mib()
            .map_err(|e| {
                crate::CoreError::ConfigError(crate::error::ErrorContext::new(format!(
                    "Failed to get mapped: {}",
                    e
                )))
            })?
            .read()
            .map_err(|e| {
                crate::CoreError::ConfigError(crate::error::ErrorContext::new(format!(
                    "Failed to read mapped: {}",
                    e
                )))
            })?;

        let metadata = stats::metadata::mib()
            .map_err(|e| {
                crate::CoreError::ConfigError(crate::error::ErrorContext::new(format!(
                    "Failed to get metadata: {}",
                    e
                )))
            })?
            .read()
            .map_err(|e| {
                crate::CoreError::ConfigError(crate::error::ErrorContext::new(format!(
                    "Failed to read metadata: {}",
                    e
                )))
            })?;

        let retained = stats::retained::mib()
            .map_err(|e| {
                crate::CoreError::ConfigError(crate::error::ErrorContext::new(format!(
                    "Failed to get retained: {}",
                    e
                )))
            })?
            .read()
            .map_err(|e| {
                crate::CoreError::ConfigError(crate::error::ErrorContext::new(format!(
                    "Failed to read retained: {}",
                    e
                )))
            })?;

        Ok(Self {
            allocated,
            resident,
            mapped,
            metadata,
            retained,
        })
    }

    /// Calculate memory overhead (metadata / allocated)
    pub fn overhead_ratio(&self) -> f64 {
        if self.allocated == 0 {
            0.0
        } else {
            self.metadata as f64 / self.allocated as f64
        }
    }

    /// Calculate memory utilization (allocated / resident)
    pub fn utilization_ratio(&self) -> f64 {
        if self.resident == 0 {
            0.0
        } else {
            self.allocated as f64 / self.resident as f64
        }
    }

    /// Format as human-readable string
    pub fn format(&self) -> String {
        format!(
            "Memory Stats:\n\
             - Allocated: {} MB\n\
             - Resident:  {} MB\n\
             - Mapped:    {} MB\n\
             - Metadata:  {} MB\n\
             - Retained:  {} MB\n\
             - Overhead:  {:.2}%\n\
             - Utilization: {:.2}%",
            self.allocated / 1_048_576,
            self.resident / 1_048_576,
            self.mapped / 1_048_576,
            self.metadata / 1_048_576,
            self.retained / 1_048_576,
            self.overhead_ratio() * 100.0,
            self.utilization_ratio() * 100.0
        )
    }
}

/// Memory profiler
#[cfg(feature = "profiling_memory")]
pub struct MemoryProfiler {
    baseline: Option<MemoryStats>,
}

#[cfg(feature = "profiling_memory")]
impl MemoryProfiler {
    /// Create a new memory profiler
    pub fn new() -> Self {
        Self { baseline: None }
    }

    /// Set the baseline memory statistics
    pub fn set_baseline(&mut self) -> CoreResult<()> {
        self.baseline = Some(MemoryStats::current()?);
        Ok(())
    }

    /// Get current memory statistics
    pub fn get_stats() -> CoreResult<MemoryStats> {
        MemoryStats::current()
    }

    /// Get memory delta from baseline
    pub fn get_delta(&self) -> CoreResult<Option<MemoryDelta>> {
        if let Some(ref baseline) = self.baseline {
            let current = MemoryStats::current()?;
            Ok(Some(MemoryDelta {
                allocated_delta: current.allocated as i64 - baseline.allocated as i64,
                resident_delta: current.resident as i64 - baseline.resident as i64,
                mapped_delta: current.mapped as i64 - baseline.mapped as i64,
                metadata_delta: current.metadata as i64 - baseline.metadata as i64,
                retained_delta: current.retained as i64 - baseline.retained as i64,
            }))
        } else {
            Ok(None)
        }
    }

    /// Print memory statistics
    pub fn print_stats() -> CoreResult<()> {
        let stats = Self::get_stats()?;
        println!("{}", stats.format());
        Ok(())
    }
}

#[cfg(feature = "profiling_memory")]
impl Default for MemoryProfiler {
    fn default() -> Self {
        Self::new()
    }
}

/// Memory delta from baseline
#[cfg(feature = "profiling_memory")]
#[derive(Debug, Clone)]
pub struct MemoryDelta {
    pub allocated_delta: i64,
    pub resident_delta: i64,
    pub mapped_delta: i64,
    pub metadata_delta: i64,
    pub retained_delta: i64,
}

#[cfg(feature = "profiling_memory")]
impl MemoryDelta {
    /// Format as human-readable string
    pub fn format(&self) -> String {
        format!(
            "Memory Delta:\n\
             - Allocated: {:+} MB\n\
             - Resident:  {:+} MB\n\
             - Mapped:    {:+} MB\n\
             - Metadata:  {:+} MB\n\
             - Retained:  {:+} MB",
            self.allocated_delta / 1_048_576,
            self.resident_delta / 1_048_576,
            self.mapped_delta / 1_048_576,
            self.metadata_delta / 1_048_576,
            self.retained_delta / 1_048_576
        )
    }
}

/// Allocation tracker for detecting patterns
#[cfg(feature = "profiling_memory")]
pub struct AllocationTracker {
    snapshots: Vec<(String, MemoryStats)>,
}

#[cfg(feature = "profiling_memory")]
impl AllocationTracker {
    /// Create a new allocation tracker
    pub fn new() -> Self {
        Self {
            snapshots: Vec::new(),
        }
    }

    /// Take a snapshot with a label
    pub fn snapshot(&mut self, label: impl Into<String>) -> CoreResult<()> {
        let stats = MemoryStats::current()?;
        self.snapshots.push((label.into(), stats));
        Ok(())
    }

    /// Get all snapshots
    pub fn snapshots(&self) -> &[(String, MemoryStats)] {
        &self.snapshots
    }

    /// Analyze allocation patterns
    pub fn analyze(&self) -> AllocationAnalysis {
        if self.snapshots.is_empty() {
            return AllocationAnalysis {
                total_allocated: 0,
                peak_allocated: 0,
                total_snapshots: 0,
                largest_increase: None,
                patterns: HashMap::new(),
            };
        }

        let mut peak_allocated = 0;
        let mut largest_increase: Option<(String, i64)> = None;

        for i in 0..self.snapshots.len() {
            let (ref label, ref stats) = self.snapshots[i];

            if stats.allocated > peak_allocated {
                peak_allocated = stats.allocated;
            }

            if i > 0 {
                let prev_stats = &self.snapshots[i - 1].1;
                let increase = stats.allocated as i64 - prev_stats.allocated as i64;

                if let Some((_, max_increase)) = largest_increase {
                    if increase > max_increase {
                        largest_increase = Some((label.clone(), increase));
                    }
                } else {
                    largest_increase = Some((label.clone(), increase));
                }
            }
        }

        let last_stats = &self
            .snapshots
            .last()
            .expect("Expected at least one snapshot")
            .1;

        AllocationAnalysis {
            total_allocated: last_stats.allocated,
            peak_allocated,
            total_snapshots: self.snapshots.len(),
            largest_increase,
            patterns: HashMap::new(),
        }
    }

    /// Clear all snapshots
    pub fn clear(&mut self) {
        self.snapshots.clear();
    }
}

#[cfg(feature = "profiling_memory")]
impl Default for AllocationTracker {
    fn default() -> Self {
        Self::new()
    }
}

/// Allocation pattern analysis
#[cfg(feature = "profiling_memory")]
#[derive(Debug, Clone)]
pub struct AllocationAnalysis {
    pub total_allocated: usize,
    pub peak_allocated: usize,
    pub total_snapshots: usize,
    pub largest_increase: Option<(String, i64)>,
    pub patterns: HashMap<String, usize>,
}

/// Enable memory profiling
#[cfg(feature = "profiling_memory")]
pub fn enable_profiling() -> CoreResult<()> {
    // In jemalloc, profiling is controlled at compile time or via environment variables
    // This is a no-op but provided for API consistency
    Ok(())
}

/// Disable memory profiling
#[cfg(feature = "profiling_memory")]
pub fn disable_profiling() -> CoreResult<()> {
    // This is a no-op but provided for API consistency
    Ok(())
}

/// Stub implementations when profiling_memory feature is disabled
#[cfg(not(feature = "profiling_memory"))]
use crate::CoreResult;

#[cfg(not(feature = "profiling_memory"))]
#[derive(Debug, Clone)]
pub struct MemoryStats {
    pub allocated: usize,
    pub resident: usize,
    pub mapped: usize,
    pub metadata: usize,
    pub retained: usize,
}

#[cfg(not(feature = "profiling_memory"))]
impl MemoryStats {
    pub fn current() -> CoreResult<Self> {
        Ok(Self {
            allocated: 0,
            resident: 0,
            mapped: 0,
            metadata: 0,
            retained: 0,
        })
    }

    pub fn format(&self) -> String {
        "Memory profiling not enabled".to_string()
    }
}

#[cfg(not(feature = "profiling_memory"))]
pub struct MemoryProfiler;

#[cfg(not(feature = "profiling_memory"))]
impl MemoryProfiler {
    pub fn new() -> Self {
        Self
    }
    pub fn get_stats() -> CoreResult<MemoryStats> {
        MemoryStats::current()
    }
    pub fn print_stats() -> CoreResult<()> {
        Ok(())
    }
}

#[cfg(not(feature = "profiling_memory"))]
pub fn enable_profiling() -> CoreResult<()> {
    Ok(())
}

#[cfg(test)]
#[cfg(feature = "profiling_memory")]
mod tests {
    use super::*;

    #[test]
    fn test_memory_stats() {
        let stats = MemoryStats::current();
        assert!(stats.is_ok());

        if let Ok(s) = stats {
            println!("{}", s.format());
        }
    }

    #[test]
    fn test_memory_profiler() {
        let mut profiler = MemoryProfiler::new();
        assert!(profiler.set_baseline().is_ok());

        // Allocate some memory
        let _vec: Vec<u8> = vec![0; 1_000_000];

        let delta = profiler.get_delta();
        assert!(delta.is_ok());
    }

    #[test]
    fn test_allocation_tracker() {
        let mut tracker = AllocationTracker::new();

        assert!(tracker.snapshot("baseline").is_ok());

        // Allocate some memory
        let _vec: Vec<u8> = vec![0; 1_000_000];

        assert!(tracker.snapshot("after_alloc").is_ok());

        let analysis = tracker.analyze();
        assert_eq!(analysis.total_snapshots, 2);
    }

    #[test]
    fn test_memory_delta() {
        let delta = MemoryDelta {
            allocated_delta: 1_048_576,
            resident_delta: 2_097_152,
            mapped_delta: 0,
            metadata_delta: 0,
            retained_delta: 0,
        };

        let formatted = delta.format();
        assert!(formatted.contains("Allocated"));
    }
}