Architecture

架构设计

核心设计原则

• 性能优先: 最大化处理吞吐量和资源利用率
• 现代 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 / 统计计算          │
└─────────────────────────────────────────────┘

1. CLI 层

• 入口: src/cli/main.cpp
• 职责: 参数解析、命令分发、日志初始化
• 依赖: cxxopts（命令行解析）+ spdlog（日志）

2. 应用命令层

• 接口: CommandInterface（command_interface.h）
• 实现: StatCommand、FilterCommand
• 职责: 参数验证、构建领域对象、调用核心库

3. 核心库层（公共 API）

• 位置: include/fqtools/
• 聚合入口: fq.h
• 主要接口:
  • processing_pipeline.h → ProcessingPipelineInterface
  • statistic_calculator.h → StatisticCalculatorInterface
  • io/fastq_reader.h → FastqReader
  • io/fastq_writer.h → FastqWriter

4. 实现层

模块	目录	职责
I/O	src/io/	FASTQ 批量读写、gzip 压缩/解压
处理	src/processing/	TBB 并行流水线、Predicate、Mutator
统计	src/statistics/	并行统计计算、结果合并
配置	src/config/	配置加载与验证
错误	src/error/	异常体系
通用	src/common/	Timer、IDGenerator 等

---

数据模型

FastqRecord — 零拷贝视图

struct FastqRecord {
    std::string_view id;        // 记录标识符
    std::string_view sequence;  // DNA 序列
    std::string_view quality;   // 质量分数
    std::string_view separator; // 分隔符行（+）
};

• 使用 std::string_view 指向 FastqBatch 的连续内存，避免字符串拷贝

FastqBatch — 批量容器

FastqBatch
├── buffer_     连续内存块（存储原始 FASTQ 文本）
└── records_    FastqRecord 数组（string_view 指向 buffer_）

• Reader 将解析结果填入 FastqBatch
• 上游处理只读写 FastqRecord（视图），无需额外分配

FastqBatchPool — 对象池

基于 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	并发批次数 (2× 线程数)
首选	batchCapacityBytes	批次内存限制
次选	专项算法优化	需要 benchmark 数据支撑
不做默认目标	SIMD/PGO	高耦合优化，需要充分证据

---

CMake 模块拆分

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 — 性能基准数据