memscope_rs/capture/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> {
        #[cfg(feature = "backtrace")]
        {
            use backtrace::Backtrace;
            let bt = Backtrace::new();

            for (i, frame) in bt.frames().iter().enumerate() {
                if frames.len() >= self.config.max_depth {
                    break;
                }

                if i < self.config.skip_frames {
                    continue;
                }

                let ip = frame.ip() as usize;

                frames.push(StackFrame {
                    ip,
                    fp: None,
                    sp: None,
                    module_base: None,
                    module_offset: None,
                    symbol_info: frame.symbols().first().map(|sym| FrameSymbolInfo {
                        name: sym
                            .name()
                            .map(|n| format!("{:?}", n))
                            .unwrap_or_else(|| format!("unknown_symbol_{i}")),
                        demangled_name: sym.name().map(|n| format!("{:?}", n)),
                        file_name: sym.filename().map(|f| f.display().to_string()),
                        line_number: sym.lineno(),
                    }),
                });
            }

            if !frames.is_empty() {
                return Ok(());
            }
        }

        #[cfg(not(feature = "backtrace"))]
        {
            self.walk_linux_stack_fallback(frames)?;
        }

        Ok(())
    }

    #[cfg(target_os = "linux")]
    #[allow(dead_code)] // Fallback for when backtrace feature is disabled
    fn walk_linux_stack_fallback(&self, frames: &mut Vec<StackFrame>) -> Result<(), WalkError> {
        use libc::{backtrace, c_void};

        struct FrameData {
            frames: *mut Vec<StackFrame>,
            max_depth: usize,
            skip_frames: usize,
            count: usize,
        }

        extern "C" fn callback(
            data: *mut c_void,
            ip: libc::uintptr_t,
            _sp: libc::uintptr_t,
            _fp: libc::uintptr_t,
        ) -> libc::c_int {
            let frame_data = match unsafe { (data as *mut FrameData).as_mut() } {
                Some(fd) => fd,
                None => return -1,
            };

            if frame_data.count < frame_data.skip_frames {
                frame_data.count += 1;
                return 0;
            }

            if frame_data.frames.is_null() {
                return -1;
            }

            let frames = unsafe { &mut *frame_data.frames };
            if frames.len() < frame_data.max_depth {
                frames.push(StackFrame {
                    ip,
                    fp: None,
                    sp: None,
                    module_base: None,
                    module_offset: None,
                    symbol_info: None,
                });
            }

            0
        }

        let mut frame_data = FrameData {
            frames: frames as *mut Vec<StackFrame>,
            max_depth: self.config.max_depth,
            skip_frames: self.config.skip_frames,
            count: 0,
        };

        unsafe {
            let mut buffer: [*mut libc::c_void; 64] = [std::ptr::null_mut(); 64];
            let result = backtrace(buffer.as_mut_ptr(), buffer.len() as libc::c_int);
            if result > 0 {
                for i in 0..result {
                    let ip = buffer[i as usize] as libc::uintptr_t;
                    let _ = callback(&mut frame_data as *mut FrameData as *mut c_void, ip, 0, 0);
                }
            }
        }

        Ok(())
    }

    #[cfg(target_os = "windows")]
    #[cfg(target_os = "windows")]
    fn walk_windows_stack(&self, _frames: &mut Vec<StackFrame>) -> Result<(), WalkError> {
        // Windows-specific stack walking using StackWalk64 or RtlCaptureStackBackTrace
        //
        // NOTE: This is a simplified implementation for demonstration.
        // A full implementation would:
        // 1. Use StackWalk64 API from DbgHelp.dll for accurate stack walking
        // 2. Use SymFromAddr and SymGetLineFromAddr64 for symbol resolution
        // 3. Handle both 32-bit and 64-bit architectures
        // 4. Support exception handling contexts
        //
        // Current implementation: Uses backtrace crate if available, otherwise simulated

        // Try to use backtrace() if available
        #[cfg(feature = "backtrace")]
        {
            use backtrace::Backtrace;
            let bt = Backtrace::new();

            for (i, frame) in bt.frames().iter().enumerate() {
                if _frames.len() >= self.config.max_depth {
                    break;
                }

                if i < self.config.skip_frames {
                    continue;
                }

                let ip = frame.ip() as usize;

                _frames.push(StackFrame {
                    ip,
                    fp: None,
                    sp: None,
                    module_base: None,
                    module_offset: None,
                    symbol_info: frame.symbols().first().map(|sym| FrameSymbolInfo {
                        name: sym
                            .name()
                            .map(|n| format!("{:?}", n))
                            .unwrap_or_else(|| format!("unknown_symbol_{i}")),
                        demangled_name: sym.name().map(|n| format!("{:?}", n)),
                        file_name: sym.filename().map(|f| f.display().to_string()),
                        line_number: sym.lineno(),
                    }),
                });
            }

            if !_frames.is_empty() {
                return Ok(());
            }
        }

        // Fallback: Simulated implementation
        tracing::warn!("Using simulated stack walking on Windows. Consider enabling 'backtrace' feature for accurate results.");

        // Fallback: Unable to get real stack frames
        tracing::warn!("Unable to capture stack frames on Windows. Backtrace feature may not be enabled or failed.");
        Ok(())
    }

    #[cfg(target_os = "macos")]
    fn walk_macos_stack(&self, frames: &mut Vec<StackFrame>) -> Result<(), WalkError> {
        use libc::{backtrace, c_void};

        const MAX_FRAMES: usize = 64;
        let mut buffer: Vec<*mut c_void> = vec![std::ptr::null_mut(); MAX_FRAMES];

        let num_frames: i32 = unsafe { backtrace(buffer.as_mut_ptr(), MAX_FRAMES as i32) };

        if num_frames <= 0 {
            return Ok(());
        }

        let num_frames_usize = num_frames as usize;

        for (i, &frame) in buffer.iter().take(num_frames_usize).enumerate() {
            if frames.len() >= self.config.max_depth {
                break;
            }

            if i < self.config.skip_frames {
                continue;
            }

            let ip = frame as usize;

            frames.push(StackFrame {
                ip,
                fp: None,
                sp: None,
                module_base: None,
                module_offset: None,
                symbol_info: None,
            });
        }

        Ok(())
    }

    #[cfg(target_os = "linux")]
    fn walk_linux_thread(&self, _thread_id: u32) -> WalkResult {
        // Linux thread-specific walking would use ptrace or /proc/[pid]/task/[tid]/stack
        // This feature is not yet implemented
        WalkResult {
            success: false,
            frames: Vec::new(),
            walk_time: Duration::ZERO,
            error: Some(WalkError::Unknown(
                "Thread-specific stack walking is not yet implemented on Linux. Would require ptrace or reading /proc/[pid]/task/[tid]/stack.".to_string(),
            )),
        }
    }

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

    #[cfg(target_os = "macos")]
    fn walk_macos_thread(&self, _thread_id: u32) -> WalkResult {
        // macOS thread-specific walking would use thread_get_state API
        // This feature is not yet implemented
        WalkResult {
            success: false,
            frames: Vec::new(),
            walk_time: Duration::ZERO,
            error: Some(WalkError::Unknown(
                "Thread-specific stack walking is not yet implemented on macOS. Would require thread_get_state API integration.".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);
                #[cfg(any(target_os = "linux", target_os = "macos"))]
                {
                    assert!(
                        !result.frames.is_empty(),
                        "Native backtrace should produce frames on Linux/macOS"
                    );
                    assert!(result.walk_time > Duration::ZERO);
                }
            }
        }
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn test_macos_native_backtrace() {
        let mut walker = PlatformStackWalker::new();
        let _ = walker.initialize();

        let mut frames = Vec::new();
        let result = walker.walk_macos_stack(&mut frames);

        assert!(result.is_ok());
        assert!(
            !frames.is_empty(),
            "macOS native backtrace should produce at least the test frame"
        );

        for frame in &frames {
            assert!(
                frame.ip > 0,
                "Each frame should have a valid instruction pointer"
            );
        }
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn test_macos_backtrace_respects_max_depth() {
        let mut walker = PlatformStackWalker::new();
        walker.config.max_depth = 3;

        let mut frames = Vec::new();
        let _ = walker.walk_macos_stack(&mut frames);

        assert!(
            frames.len() <= 3,
            "Should respect max_depth limit, got {} frames",
            frames.len()
        );
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn test_macos_backtrace_respects_skip_frames() {
        let mut walker = PlatformStackWalker::new();
        walker.config.skip_frames = 2;

        let mut frames = Vec::new();
        let _ = walker.walk_macos_stack(&mut frames);

        if frames.len() > 2 {
            assert!(
                frames[0].ip != frames[1].ip || frames.len() < 3,
                "First frames should be skipped"
            );
        }
    }

    #[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));
    }
}