-
Notifications
You must be signed in to change notification settings - Fork 0
Architecture
shijiashuai edited this page Mar 9, 2026
·
1 revision
- 性能优先: 最大化处理吞吐量和资源利用率
- 现代 C++: 全面使用 C++23 标准特性
- 高内聚低耦合: 清晰的模块边界和接口设计
- 测量驱动: 性能优化必须以 benchmark 数据为依据
┌─────────────────────────────────────────────┐
│ 用户 / 调用者 │
├─────────────────────────────────────────────┤
│ CLI 层 (src/cli/) │
│ main.cpp → 参数解析 → 命令分发 │
├─────────────────────────────────────────────┤
│ 应用命令层 (src/cli/commands/) │
│ StatCommand / FilterCommand │
├─────────────────────────────────────────────┤
│ 核心库层 (include/fqtools/) │
│ ProcessingPipelineInterface │
│ StatisticCalculatorInterface │
│ FastqReader / FastqWriter │
├─────────────────────────────────────────────┤
│ 实现层 (src/processing, io, statistics) │
│ TBB 并行流水线 / 批量 I/O / 统计计算 │
└─────────────────────────────────────────────┘
-
入口:
src/cli/main.cpp - 职责: 参数解析、命令分发、日志初始化
- 依赖: cxxopts(命令行解析)+ spdlog(日志)
-
接口:
CommandInterface(command_interface.h) -
实现:
StatCommand、FilterCommand - 职责: 参数验证、构建领域对象、调用核心库
-
位置:
include/fqtools/ -
聚合入口:
fq.h -
主要接口:
-
processing_pipeline.h→ProcessingPipelineInterface -
statistic_calculator.h→StatisticCalculatorInterface -
io/fastq_reader.h→FastqReader -
io/fastq_writer.h→FastqWriter
-
| 模块 | 目录 | 职责 |
|---|---|---|
| I/O | src/io/ |
FASTQ 批量读写、gzip 压缩/解压 |
| 处理 | src/processing/ |
TBB 并行流水线、Predicate、Mutator |
| 统计 | src/statistics/ |
并行统计计算、结果合并 |
| 配置 | src/config/ |
配置加载与验证 |
| 错误 | src/error/ |
异常体系 |
| 通用 | src/common/ |
Timer、IDGenerator 等 |
struct FastqRecord { std::string_view id; // 记录标识符 std::string_view sequence; // DNA 序列 std::string_view quality; // 质量分数 std::string_view separator; // 分隔符行(+) };
- 使用
std::string_view指向FastqBatch的连续内存,避免字符串拷贝
FastqBatch
├── buffer_ 连续内存块(存储原始 FASTQ 文本)
└── records_ FastqRecord 数组(string_view 指向 buffer_)
- Reader 将解析结果填入
FastqBatch - 上游处理只读写
FastqRecord(视图),无需额外分配
基于 ObjectPool<FastqBatch> 实现,减少 TBB pipeline 中的频繁分配与回收。
使用 tbb::parallel_pipeline 实现三阶段流水线:
┌──────────┐ ┌───────────────┐ ┌──────────┐
│ Source │───▶│ Processing │───▶│ Sink │
│ (serial) │ │ (parallel) │ │ (serial) │
└──────────┘ └───────────────┘ └──────────┘
串行读取 并行过滤/修剪 串行写入
FastqBatch Predicate+Mutator 有序输出
-
Source(serial_in_order): 串行从文件读取
FastqBatch - Processing(parallel): 并行对 batch 执行 predicates/mutators 并统计
- Sink(serial_in_order): 按顺序写出结果,合并统计数据
-
背压机制: 通过
maxInFlightBatches控制内存使用,自动平衡 I/O 和计算速度
ProcessingPipeline::run() 根据 threadCount 自动选择:
-
threadCount == 1→processSequential()(便于调试、小文件) -
threadCount > 1→processWithTBB()(生产场景)
按优先级排列:
| 优先级 | 参数 | 说明 |
|---|---|---|
| 首选 | batchSize |
每批 reads 数量 (10K–100K) |
| 首选 | threadCount |
并行线程数 |
| 首选 | maxInFlightBatches |
并发批次数 (×ばつ 线程数) |
| 首选 | batchCapacityBytes |
批次内存限制 |
| 次选 | 专项算法优化 | 需要 benchmark 数据支撑 |
| 不做默认目标 | SIMD/PGO | 高耦合优化,需要充分证据 |
fq_common ← Timer, IDGenerator
fq_error ← FastQException 异常体系
fq_config ← Configuration 配置管理
fq_modern_io ← FastqReader / FastqWriter
fq_processing ← ProcessingPipeline / Predicate / Mutator
fq_statistics ← StatisticCalculator
fq_cli ← CommandInterface / StatCommand / FilterCommand
依赖方向保持自下而上:fq_cli → fq_processing → fq_modern_io → fq_common
find_package(FastQTools REQUIRED) target_link_libraries(my_app PRIVATE FastQTools::FastQTools)
fastq-tools/
├── include/fqtools/ # 公共 API 头文件(对外接口)
├── src/ # 源代码实现
│ ├── cli/ # CLI 入口与命令
│ ├── common/ # 通用工具
│ ├── config/ # 配置管理
│ ├── error/ # 错误处理
│ ├── io/ # I/O 层
│ ├── processing/ # 处理流水线
│ └── statistics/ # 统计分析
├── tests/ # 测试(unit / integration / e2e)
├── tools/ # 开发工具(benchmark / fuzz / data)
├── config/ # 构建配置(Conan / sanitizers / valgrind)
├── scripts/ # 构建与工具脚本
├── docker/ # Docker 配置
├── docs/ # 项目文档
├── examples/ # 使用示例
└── changelog/ # 变更记录
- API Reference — 详细 C++ API 文档
- Build and CI — 构建系统详解
- Performance Benchmarks — 性能基准数据
FastQTools v3.1.0
🚀 快速上手
🏗️ 架构与设计
🔧 构建与部署
🧪 质量工程
📖 规范与参考
🔗 外部链接