memscope_rs/platform/

stack_walker.rs

use std::time::{Duration, Instant};

/// Platform-specific stack walking implementation
pub struct PlatformStackWalker {
    /// Walker configuration
    config: StackWalkConfig,
    /// Performance statistics
    stats: WalkStats,
    /// Platform-specific context
    platform_context: PlatformContext,
}

/// Configuration for stack walking
#[derive(Debug, Clone)]
pub struct StackWalkConfig {
    /// Maximum depth to walk
    pub max_depth: usize,
    /// Number of frames to skip at top
    pub skip_frames: usize,
    /// Whether to use fast unwinding
    pub fast_unwind: bool,
    /// Whether to collect frame info
    pub collect_frame_info: bool,
    /// Maximum time to spend walking
    pub max_walk_time: Duration,
}

/// Platform-specific context for stack walking
#[derive(Debug)]
struct PlatformContext {
    /// Whether unwinder is initialized
    initialized: bool,
    /// Platform-specific data
    #[cfg(target_os = "linux")]
    linux_context: LinuxContext,
    #[cfg(target_os = "windows")]
    windows_context: WindowsContext,
    #[cfg(target_os = "macos")]
    macos_context: MacOSContext,
}

/// Linux-specific context
#[cfg(target_os = "linux")]
#[derive(Debug)]
struct LinuxContext {
    /// Whether libunwind is available
    libunwind_available: bool,
    /// Whether DWARF info is available
    dwarf_available: bool,
}

/// Windows-specific context
#[cfg(target_os = "windows")]
#[derive(Debug)]
struct WindowsContext {
    /// Whether RtlCaptureStackBackTrace is available
    capture_available: bool,
    /// Whether symbol APIs are initialized
    symbols_initialized: bool,
}

/// macOS-specific context
#[cfg(target_os = "macos")]
#[derive(Debug)]
struct MacOSContext {
    /// Whether backtrace() is available
    backtrace_available: bool,
    /// Whether dSYM files are accessible
    dsym_available: bool,
}

/// Statistics for stack walking performance
#[derive(Debug)]
struct WalkStats {
    /// Total walks performed
    total_walks: std::sync::atomic::AtomicUsize,
    /// Total frames collected
    total_frames: std::sync::atomic::AtomicUsize,
    /// Total time spent walking
    total_walk_time: std::sync::atomic::AtomicU64,
    /// Failed walks
    failed_walks: std::sync::atomic::AtomicUsize,
}

/// Result of stack walk operation
#[derive(Debug, Clone)]
pub struct WalkResult {
    /// Success status
    pub success: bool,
    /// Collected stack frames
    pub frames: Vec<StackFrame>,
    /// Time taken for walk
    pub walk_time: Duration,
    /// Error if walk failed
    pub error: Option<WalkError>,
}

/// Individual stack frame information
#[derive(Debug, Clone)]
pub struct StackFrame {
    /// Instruction pointer
    pub ip: usize,
    /// Frame pointer
    pub fp: Option<usize>,
    /// Stack pointer
    pub sp: Option<usize>,
    /// Module base address
    pub module_base: Option<usize>,
    /// Offset within module
    pub module_offset: Option<usize>,
    /// Symbol information if available
    pub symbol_info: Option<FrameSymbolInfo>,
}

/// Symbol information for a frame
#[derive(Debug, Clone)]
pub struct FrameSymbolInfo {
    /// Symbol name
    pub name: String,
    /// Demangled name
    pub demangled_name: Option<String>,
    /// File name
    pub file_name: Option<String>,
    /// Line number
    pub line_number: Option<u32>,
}

/// Errors that can occur during stack walking
#[derive(Debug, Clone, PartialEq)]
pub enum WalkError {
    /// Platform not supported
    UnsupportedPlatform,
    /// Unwind library not available
    UnwindUnavailable,
    /// Insufficient permissions
    InsufficientPermissions,
    /// Corrupted stack
    CorruptedStack,
    /// Timeout during walk
    Timeout,
    /// Memory access error
    MemoryError,
    /// Unknown error
    Unknown(String),
}

impl PlatformStackWalker {
    /// Create new platform stack walker
    pub fn new() -> Self {
        Self {
            config: StackWalkConfig::default(),
            stats: WalkStats::new(),
            platform_context: PlatformContext::new(),
        }
    }

    /// Initialize stack walker for current platform
    pub fn initialize(&mut self) -> Result<(), WalkError> {
        #[cfg(target_os = "linux")]
        {
            self.initialize_linux()
        }

        #[cfg(target_os = "windows")]
        {
            self.initialize_windows()
        }

        #[cfg(target_os = "macos")]
        {
            self.initialize_macos()
        }

        #[cfg(not(any(target_os = "linux", target_os = "windows", target_os = "macos")))]
        {
            Err(WalkError::UnsupportedPlatform)
        }
    }

    /// Walk current thread's stack
    pub fn walk_current_thread(&mut self) -> WalkResult {
        let start_time = Instant::now();

        if !self.platform_context.initialized {
            return WalkResult {
                success: false,
                frames: Vec::new(),
                walk_time: start_time.elapsed(),
                error: Some(WalkError::UnwindUnavailable),
            };
        }

        let result = self.perform_stack_walk();
        let walk_time = start_time.elapsed();

        // Update statistics
        self.stats
            .total_walks
            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        if result.success {
            self.stats
                .total_frames
                .fetch_add(result.frames.len(), std::sync::atomic::Ordering::Relaxed);
        } else {
            self.stats
                .failed_walks
                .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        }
        self.stats.total_walk_time.fetch_add(
            walk_time.as_nanos() as u64,
            std::sync::atomic::Ordering::Relaxed,
        );

        WalkResult {
            success: result.success,
            frames: result.frames,
            walk_time,
            error: result.error,
        }
    }

    /// Walk specific thread's stack
    pub fn walk_thread(&mut self, thread_id: u32) -> WalkResult {
        // Platform-specific thread stack walking
        #[cfg(target_os = "linux")]
        {
            self.walk_linux_thread(thread_id)
        }

        #[cfg(target_os = "windows")]
        {
            self.walk_windows_thread(thread_id)
        }

        #[cfg(target_os = "macos")]
        {
            self.walk_macos_thread(thread_id)
        }

        #[cfg(not(any(target_os = "linux", target_os = "windows", target_os = "macos")))]
        {
            WalkResult {
                success: false,
                frames: Vec::new(),
                walk_time: Duration::ZERO,
                error: Some(WalkError::UnsupportedPlatform),
            }
        }
    }

    /// Get walking statistics
    pub fn get_statistics(&self) -> WalkStatistics {
        let total_walks = self
            .stats
            .total_walks
            .load(std::sync::atomic::Ordering::Relaxed);
        let total_frames = self
            .stats
            .total_frames
            .load(std::sync::atomic::Ordering::Relaxed);
        let total_time_ns = self
            .stats
            .total_walk_time
            .load(std::sync::atomic::Ordering::Relaxed);
        let failed_walks = self
            .stats
            .failed_walks
            .load(std::sync::atomic::Ordering::Relaxed);

        WalkStatistics {
            total_walks,
            successful_walks: total_walks.saturating_sub(failed_walks),
            failed_walks,
            total_frames_collected: total_frames,
            average_frames_per_walk: if total_walks > 0 {
                total_frames as f64 / total_walks as f64
            } else {
                0.0
            },
            average_walk_time: if total_walks > 0 {
                Duration::from_nanos(total_time_ns / total_walks as u64)
            } else {
                Duration::ZERO
            },
            success_rate: if total_walks > 0 {
                (total_walks - failed_walks) as f64 / total_walks as f64
            } else {
                0.0
            },
        }
    }

    /// Update walker configuration
    pub fn update_config(&mut self, config: StackWalkConfig) {
        self.config = config;
    }

    fn perform_stack_walk(&self) -> WalkResult {
        let mut frames = Vec::with_capacity(self.config.max_depth);
        let start_time = Instant::now();

        #[cfg(target_os = "linux")]
        let result = self.walk_linux_stack(&mut frames);

        #[cfg(target_os = "windows")]
        let result = self.walk_windows_stack(&mut frames);

        #[cfg(target_os = "macos")]
        let result = self.walk_macos_stack(&mut frames);

        #[cfg(not(any(target_os = "linux", target_os = "windows", target_os = "macos")))]
        let result = Err(WalkError::UnsupportedPlatform);

        match result {
            Ok(()) => WalkResult {
                success: true,
                frames,
                walk_time: start_time.elapsed(),
                error: None,
            },
            Err(error) => WalkResult {
                success: false,
                frames,
                walk_time: start_time.elapsed(),
                error: Some(error),
            },
        }
    }

    #[cfg(target_os = "linux")]
    fn initialize_linux(&mut self) -> Result<(), WalkError> {
        // Check for libunwind availability
        self.platform_context.linux_context.libunwind_available = true; // Simplified
        self.platform_context.linux_context.dwarf_available = true; // Simplified
        self.platform_context.initialized = true;
        Ok(())
    }

    #[cfg(target_os = "windows")]
    fn initialize_windows(&mut self) -> Result<(), WalkError> {
        // Initialize Windows stack walking APIs
        self.platform_context.windows_context.capture_available = true; // Simplified
        self.platform_context.windows_context.symbols_initialized = true; // Simplified
        self.platform_context.initialized = true;
        Ok(())
    }

    #[cfg(target_os = "macos")]
    fn initialize_macos(&mut self) -> Result<(), WalkError> {
        // Initialize macOS stack walking
        self.platform_context.macos_context.backtrace_available = true; // Simplified
        self.platform_context.macos_context.dsym_available = true; // Simplified
        self.platform_context.initialized = true;
        Ok(())
    }

    #[cfg(target_os = "linux")]
    fn walk_linux_stack(&self, frames: &mut Vec<StackFrame>) -> Result<(), WalkError> {
        // Linux-specific stack walking using libunwind or similar
        // This is a simplified implementation
        for i in 0..self.config.max_depth.min(10) {
            if i < self.config.skip_frames {
                continue;
            }

            frames.push(StackFrame {
                ip: 0x400000 + i * 0x1000, // Mock addresses
                fp: Some(0x7fff0000 + i * 0x100),
                sp: Some(0x7fff0000 + i * 0x100 - 8),
                module_base: Some(0x400000),
                module_offset: Some(i * 0x1000),
                symbol_info: Some(FrameSymbolInfo {
                    name: format!("function_{}", i),
                    demangled_name: Some(format!("namespace::function_{}", i)),
                    file_name: Some("src/main.rs".to_string()),
                    line_number: Some((i * 10 + 100) as u32),
                }),
            });
        }
        Ok(())
    }

    #[cfg(target_os = "windows")]
    fn walk_windows_stack(&self, frames: &mut Vec<StackFrame>) -> Result<(), WalkError> {
        // Windows-specific stack walking using StackWalk64 or RtlCaptureStackBackTrace
        // This is a simplified implementation
        for i in 0..self.config.max_depth.min(10) {
            if i < self.config.skip_frames {
                continue;
            }

            frames.push(StackFrame {
                ip: 0x140000000 + i * 0x1000, // Mock addresses for x64
                fp: Some(0x000000000022f000 + i * 0x100),
                sp: Some(0x000000000022f000 + i * 0x100 - 8),
                module_base: Some(0x140000000),
                module_offset: Some(i * 0x1000),
                symbol_info: Some(FrameSymbolInfo {
                    name: format!("function_{}", i),
                    demangled_name: None,
                    file_name: Some("main.cpp".to_string()),
                    line_number: Some((i * 10 + 100) as u32),
                }),
            });
        }
        Ok(())
    }

    #[cfg(target_os = "macos")]
    fn walk_macos_stack(&self, frames: &mut Vec<StackFrame>) -> Result<(), WalkError> {
        // macOS-specific stack walking using backtrace() or similar
        // This is a simplified implementation
        for i in 0..self.config.max_depth.min(10) {
            if i < self.config.skip_frames {
                continue;
            }

            frames.push(StackFrame {
                ip: 0x100000000 + i * 0x1000, // Mock addresses
                fp: Some(0x7fff5fc00000 + i * 0x100),
                sp: Some(0x7fff5fc00000 + i * 0x100 - 8),
                module_base: Some(0x100000000),
                module_offset: Some(i * 0x1000),
                symbol_info: Some(FrameSymbolInfo {
                    name: format!("function_{}", i),
                    demangled_name: Some(format!("MyClass::function_{}", i)),
                    file_name: Some("main.mm".to_string()),
                    line_number: Some((i * 10 + 100) as u32),
                }),
            });
        }
        Ok(())
    }

    #[cfg(target_os = "linux")]
    fn walk_linux_thread(&self, _thread_id: u32) -> WalkResult {
        // Linux thread-specific walking would use ptrace or similar
        WalkResult {
            success: false,
            frames: Vec::new(),
            walk_time: Duration::ZERO,
            error: Some(WalkError::Unknown(
                "Thread walking not implemented".to_string(),
            )),
        }
    }

    #[cfg(target_os = "windows")]
    fn walk_windows_thread(&self, _thread_id: u32) -> WalkResult {
        // Windows thread-specific walking would use OpenThread + StackWalk64
        WalkResult {
            success: false,
            frames: Vec::new(),
            walk_time: Duration::ZERO,
            error: Some(WalkError::Unknown(
                "Thread walking not implemented".to_string(),
            )),
        }
    }

    #[cfg(target_os = "macos")]
    fn walk_macos_thread(&self, _thread_id: u32) -> WalkResult {
        // macOS thread-specific walking would use thread_get_state
        WalkResult {
            success: false,
            frames: Vec::new(),
            walk_time: Duration::ZERO,
            error: Some(WalkError::Unknown(
                "Thread walking not implemented".to_string(),
            )),
        }
    }
}

impl PlatformContext {
    fn new() -> Self {
        Self {
            initialized: false,
            #[cfg(target_os = "linux")]
            linux_context: LinuxContext {
                libunwind_available: false,
                dwarf_available: false,
            },
            #[cfg(target_os = "windows")]
            windows_context: WindowsContext {
                capture_available: false,
                symbols_initialized: false,
            },
            #[cfg(target_os = "macos")]
            macos_context: MacOSContext {
                backtrace_available: false,
                dsym_available: false,
            },
        }
    }
}

impl WalkStats {
    fn new() -> Self {
        Self {
            total_walks: std::sync::atomic::AtomicUsize::new(0),
            total_frames: std::sync::atomic::AtomicUsize::new(0),
            total_walk_time: std::sync::atomic::AtomicU64::new(0),
            failed_walks: std::sync::atomic::AtomicUsize::new(0),
        }
    }
}

/// Statistics about stack walking performance
#[derive(Debug, Clone)]
pub struct WalkStatistics {
    /// Total number of walks performed
    pub total_walks: usize,
    /// Number of successful walks
    pub successful_walks: usize,
    /// Number of failed walks
    pub failed_walks: usize,
    /// Total frames collected across all walks
    pub total_frames_collected: usize,
    /// Average frames per successful walk
    pub average_frames_per_walk: f64,
    /// Average time per walk
    pub average_walk_time: Duration,
    /// Success rate (0.0 to 1.0)
    pub success_rate: f64,
}

impl Default for StackWalkConfig {
    fn default() -> Self {
        Self {
            max_depth: 32,
            skip_frames: 2,
            fast_unwind: true,
            collect_frame_info: true,
            max_walk_time: Duration::from_millis(10),
        }
    }
}

impl Default for PlatformStackWalker {
    fn default() -> Self {
        Self::new()
    }
}

impl std::fmt::Display for WalkError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            WalkError::UnsupportedPlatform => write!(f, "Platform not supported for stack walking"),
            WalkError::UnwindUnavailable => write!(f, "Stack unwinding library not available"),
            WalkError::InsufficientPermissions => {
                write!(f, "Insufficient permissions for stack walking")
            }
            WalkError::CorruptedStack => write!(f, "Stack appears to be corrupted"),
            WalkError::Timeout => write!(f, "Stack walk timed out"),
            WalkError::MemoryError => write!(f, "Memory access error during stack walk"),
            WalkError::Unknown(msg) => write!(f, "Unknown error: {}", msg),
        }
    }
}

impl std::error::Error for WalkError {}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_platform_stack_walker_creation() {
        let walker = PlatformStackWalker::new();
        assert!(!walker.platform_context.initialized);

        let stats = walker.get_statistics();
        assert_eq!(stats.total_walks, 0);
        assert_eq!(stats.success_rate, 0.0);
    }

    #[test]
    fn test_stack_walk_config() {
        let config = StackWalkConfig::default();
        assert_eq!(config.max_depth, 32);
        assert_eq!(config.skip_frames, 2);
        assert!(config.fast_unwind);
        assert!(config.collect_frame_info);
    }

    #[test]
    fn test_initialization() {
        let mut walker = PlatformStackWalker::new();
        let result = walker.initialize();

        // Should succeed on supported platforms
        #[cfg(any(target_os = "linux", target_os = "windows", target_os = "macos"))]
        assert!(result.is_ok());

        #[cfg(not(any(target_os = "linux", target_os = "windows", target_os = "macos")))]
        assert_eq!(result, Err(WalkError::UnsupportedPlatform));
    }

    #[test]
    fn test_current_thread_walk() {
        let mut walker = PlatformStackWalker::new();
        let _ = walker.initialize();

        let result = walker.walk_current_thread();

        #[cfg(any(target_os = "linux", target_os = "windows", target_os = "macos"))]
        {
            if walker.platform_context.initialized {
                assert!(result.success);
                assert!(!result.frames.is_empty());
                assert!(result.walk_time > Duration::ZERO);
            }
        }
    }

    #[test]
    fn test_frame_information() {
        let frame = StackFrame {
            ip: 0x12345678,
            fp: Some(0x7fff0000),
            sp: Some(0x7fff0008),
            module_base: Some(0x12340000),
            module_offset: Some(0x5678),
            symbol_info: Some(FrameSymbolInfo {
                name: "test_function".to_string(),
                demangled_name: Some("namespace::test_function".to_string()),
                file_name: Some("test.rs".to_string()),
                line_number: Some(42),
            }),
        };

        assert_eq!(frame.ip, 0x12345678);
        assert_eq!(frame.fp, Some(0x7fff0000));
        assert!(frame.symbol_info.is_some());

        let symbol = frame
            .symbol_info
            .as_ref()
            .expect("Symbol info should exist");
        assert_eq!(symbol.name, "test_function");
        assert_eq!(symbol.line_number, Some(42));
    }
}