# 查询模块 (Query Module)
## 概述
查询模块为内存快照数据提供统一的查询接口。它支持各种查询类型和过滤选项，实现灵活的内存使用模式分析。
## 组件
### 1. QueryEngine（查询引擎）
**文件**: `src/query/engine.rs`
**用途**: 内存数据的统一查询接口。
**核心功能**:
- 统一：所有查询类型的单一接口
- 高效：针对快速查询执行进行优化
- 灵活：支持过滤和排序
- 线程安全：并发访问安全
**核心实现**:
```rust
pub struct QueryEngine {
/// 快照引擎的引用
snapshot_engine: SharedSnapshotEngine,
}
impl QueryEngine {
/// 创建新的 QueryEngine
pub fn new(snapshot_engine: SharedSnapshotEngine) -> Self {
Self { snapshot_engine }
}
/// 获取当前快照
fn get_snapshot(&self) -> MemorySnapshot {
self.snapshot_engine.build_snapshot()
}
/// 按大小查询顶级分配
pub fn top_allocations(&self, limit: usize) -> QueryResult {
let snapshot = self.get_snapshot();
let mut allocations: Vec<_> = snapshot.active_allocations.values().cloned().collect();
// 按大小降序排序
allocations.sort_by_key(|b| std::cmp::Reverse(b.size));
// 限制结果
allocations.truncate(limit);
let total_bytes = allocations.iter().map(|a| a.size).sum();
QueryResult::Allocations(AllocationQueryResult {
count: allocations.len(),
total_bytes,
allocations,
})
}
/// 查询特定线程的分配
pub fn allocations_by_thread(&self, thread_id: u64) -> QueryResult {
let snapshot = self.get_snapshot();
let allocations: Vec<_> = snapshot.active_allocations.values()
.filter(|a| a.thread_id == thread_id)
.cloned()
.collect();
let total_bytes = allocations.iter().map(|a| a.size).sum();
QueryResult::Allocations(AllocationQueryResult {
count: allocations.len(),
total_bytes,
allocations,
})
}
/// 查询线程统计
pub fn thread_stats(&self) -> QueryResult {
let snapshot = self.get_snapshot();
let threads: Vec<_> = snapshot.thread_stats.values().cloned().collect();
let total_bytes = threads.iter().map(|t| t.total_allocated).sum();
QueryResult::Threads(ThreadQueryResult {
count: threads.len(),
total_bytes,
threads,
})
}
/// 查询内存使用摘要
pub fn summary(&self) -> QueryResult {
let snapshot = self.get_snapshot();
QueryResult::Summary(SummaryQueryResult {
total_allocations: snapshot.stats.total_allocations,
total_deallocations: snapshot.stats.total_deallocations,
active_allocations: snapshot.stats.active_allocations,
total_allocated: snapshot.stats.total_allocated,
total_deallocated: snapshot.stats.total_deallocated,
current_memory: snapshot.stats.current_memory,
peak_memory: snapshot.stats.peak_memory,
thread_count: snapshot.thread_stats.len(),
})
}
/// 查询具有特定变量名的分配
pub fn allocations_by_variable(&self, var_name: &str) -> QueryResult {
let snapshot = self.get_snapshot();
let allocations: Vec<_> = snapshot.active_allocations.values()
.filter(|a| a.var_name.as_ref().map(|n| n == var_name).unwrap_or(false))
.cloned()
.collect();
let total_bytes = allocations.iter().map(|a| a.size).sum();
QueryResult::Allocations(AllocationQueryResult {
count: allocations.len(),
total_bytes,
allocations,
})
}
/// 查询大于特定大小的分配
pub fn allocations_larger_than(&self, min_size: usize) -> QueryResult {
let snapshot = self.get_snapshot();
let allocations: Vec<_> = snapshot.active_allocations.values()
.filter(|a| a.size > min_size)
.cloned()
.collect();
let total_bytes = allocations.iter().map(|a| a.size).sum();
QueryResult::Allocations(AllocationQueryResult {
count: allocations.len(),
total_bytes,
allocations,
})
}
}
```
### 2. 查询类型
**文件**: `src/query/types.rs`
**用途**: 查询结果的类型定义。
**查询结果**:
```rust
pub enum QueryResult {
/// 分配查询结果
Allocations(AllocationQueryResult),
/// 线程查询结果
Threads(ThreadQueryResult),
/// 摘要查询结果
Summary(SummaryQueryResult),
}
pub struct AllocationQueryResult {
pub count: usize,
pub total_bytes: usize,
pub allocations: Vec<ActiveAllocation>,
}
pub struct ThreadQueryResult {
pub count: usize,
pub total_bytes: usize,
pub threads: Vec<ThreadMemoryStats>,
}
pub struct SummaryQueryResult {
pub total_allocations: usize,
pub total_deallocations: usize,
pub active_allocations: usize,
pub total_allocated: usize,
pub total_deallocated: usize,
pub current_memory: usize,
pub peak_memory: usize,
pub thread_count: usize,
}
```
## 使用示例
### 基本使用
```rust
use memscope::query::QueryEngine;
use memscope::snapshot::SnapshotEngine;
use std::sync::Arc;
// 创建查询引擎
let event_store = Arc::new(EventStore::new());
let snapshot_engine = Arc::new(SnapshotEngine::new(event_store));
let query_engine = QueryEngine::new(snapshot_engine);
// 查询摘要
let result = query_engine.summary();
match result {
QueryResult::Summary(summary) => {
println!("总分配: {}", summary.total_allocations);
println!("当前内存: {} 字节", summary.current_memory);
}
_ => {}
}
```
### 查询顶级分配
```rust
// 获取按大小排序的前 10 个分配
let result = query_engine.top_allocations(10);
match result {
QueryResult::Allocations(allocations) => {
println!("顶级分配:");
for alloc in &allocations.allocations {
println!(" 0x{:x}: {} 字节", alloc.ptr, alloc.size);
}
}
_ => {}
}
```
### 按线程查询
```rust
// 获取线程 1 的分配
let result = query_engine.allocations_by_thread(1);
match result {
QueryResult::Allocations(allocations) => {
println!("线程 1 分配: {}", allocations.count);
}
_ => {}
}
```
### 查询大分配
```rust
// 查找大于 1MB 的分配
let result = query_engine.allocations_larger_than(1024 * 1024);
match result {
QueryResult::Allocations(allocations) => {
println!("大分配: {}", allocations.count);
}
_ => {}
}
```
## 设计原则
### 1. 统一接口
所有查询类型的单一接口：
- **优势**: 一致的 API，更易使用
- **权衡**: 特定查询的灵活性较低
### 2. 类型安全
查询结果的强类型：
- **优势**: 编译时安全，更好的文档
- **权衡**: 代码更冗长
### 3. 高效性
针对快速查询执行进行优化：
- **优势**: 快速分析
- **权衡**: 缓存可能使用更多内存
## 最佳实践
1. **查询优化**: 尽可能使用特定查询
2. **结果处理**: 始终处理所有查询结果类型
3. **线程安全**: 使用 Arc<QueryEngine> 进行共享访问
4. **错误处理**: 始终处理查询错误
## 限制
1. **基于快照**: 查询操作于快照，而非实时数据
2. **内存使用**: 查询结果可能很大
3. **性能**: 复杂查询可能较慢
4. **过滤**: 过滤功能有限
## 未来改进
1. **高级过滤**: 更强大的过滤选项
2. **聚合查询**: 分组、求和、平均值等
3. **基于时间的查询**: 按时间范围查询
4. **自定义查询**: 允许自定义查询逻辑
5. **查询缓存**: 缓存查询结果