memscope_rs/async_memory/
mod.rs

1//! Async Task-Centric Memory Tracking
2//!
3//! This module provides task-aware memory tracking for async/await applications.
4//! Unlike thread-based tracking, this system tracks memory allocation at the
5//! granularity of individual async tasks (Futures).
6//!
7//! Key features:
8//! - Zero-overhead task identification using Context waker addresses
9//! - Lock-free event buffering with quality monitoring
10//! - Dual-track approach: TrackedFuture + tracing::Subscriber integration
11//! - Production-grade reliability with data integrity monitoring
12//!
13//! Performance characteristics:
14//! - < 5ns per allocation tracking overhead
15//! - < 0.1% CPU overhead in typical workloads
16//! - < 1MB memory overhead per thread
17//! - Lock-free, unwrap-free, clone-free design
18//!
19/// Usage:
20/// ```rust,no_run
21/// use memscope_rs::async_memory;
22///
23/// #[tokio::main]
24/// async fn main() -> Result<(), async_memory::AsyncError> {
25///     // Initialize tracking
26///     async_memory::initialize()?;
27///     
28///     // Use tracked spawn
29///     let handle = async_memory::spawn_tracked(async {
30///         let data = vec![0u8; 1024 * 1024]; // 1MB allocation
31///         // Process the data here
32///         data.len()
33///     });
34///     
35///     let result = handle.await;
36///     println!("Processed {} bytes", result);
37///     
38///     // Get memory statistics
39///     let snapshot = async_memory::get_memory_snapshot();
40///     println!("Tasks tracked: {}", snapshot.active_task_count());
41///     
42///     Ok(())
43/// }
44/// ```
45pub mod allocator;
46pub mod api;
47pub mod buffer;
48pub mod error;
49pub mod profile;
50pub mod resource_monitor;
51pub mod system_monitor;
52pub mod task_id;
53pub mod tracker;
54pub mod visualization;
55
56// Re-export main types and functions
57pub use api::{
58    create_tracked, get_memory_snapshot, initialize, spawn_tracked, AsyncMemorySnapshot,
59};
60pub use error::AsyncError;
61pub use profile::{TaskMemoryProfile, TaskPerformanceMetrics};
62pub use resource_monitor::{
63    AsyncResourceMonitor, BottleneckType, CpuMetrics, GpuMetrics, IoMetrics, MemoryMetrics,
64    NetworkMetrics, TaskResourceProfile, TaskType,
65};
66pub use task_id::{TaskId, TaskInfo};
67pub use tracker::{TaskMemoryTracker, TrackedFuture};
68pub use visualization::{
69    CategoryRanking, ComparisonType, PerformanceBaselines, PerformanceComparison, Theme,
70    VisualizationConfig, VisualizationError, VisualizationGenerator,
71};
72
73/// Current version of the async memory tracking system
74pub const VERSION: &str = "1.1.0";
75
76/// Maximum number of tracked tasks before oldest are evicted
77pub const MAX_TRACKED_TASKS: usize = 65536;
78
79/// Default buffer size per thread for allocation events
80pub const DEFAULT_BUFFER_SIZE: usize = 1024 * 1024; // 1M events
81
82/// Compile-time assertion macro
83macro_rules! const_assert_eq {
84    ($left:expr, $right:expr) => {
85        const _: [(); 1] = [(); ($left == $right) as usize];
86    };
87}
88
89// Buffer size must be power of 2 for efficient masking
90const_assert_eq!(DEFAULT_BUFFER_SIZE & (DEFAULT_BUFFER_SIZE - 1), 0);
91
92#[cfg(test)]
93mod tests {
94    use super::*;
95
96    #[test]
97    fn test_version_format() {
98        // Ensure version follows semantic versioning
99        let parts: Vec<&str> = VERSION.split('.').collect();
100        assert_eq!(parts.len(), 3);
101
102        for part in parts {
103            assert!(part.parse::<u32>().is_ok());
104        }
105    }
106}
memscope_rs/async_memory/mod.rs

memscope_rs/async_memory/
mod.rs
