📚 课程目录第4章流图数据流

4、流图数据流：数据流方向、流标签、消息传递与流图执行模型

GNU Radio 流图（Flowgraph）的本质是一个有向数据流计算网络。理解数据在模块之间如何流动、如何被标注、如何跨越采样域的边界进行事件通信，以及调度器如何驱动整个图运转，是设计高性能、低延迟、可维护信号处理链路的基础。本章将深入剖析流图内部的数据通路机制，从同步数据流、流标签（Stream Tag）到异步消息传递（Message Passing），并揭示 GNU Radio 调度器的执行模型与线程模型。

上图展示了 GNU Radio 流图中两种并行存在的数据通路：左侧的同步采样流（实线）与右侧的异步消息流（虚线）。采样流以连续数组形式在模块间传递，具有严格的时序关系；消息流则以事件驱动方式传递 PDU（Protocol Data Unit）或控制命令，两者在调度器层面协同工作。理解这一双域模型，是掌握流图数据流的关键起点。

4.1 数据流方向与同步数据流模型

核心原理：GNU Radio 的流图基于 同步数据流图（Synchronous Dataflow, SDF） 模型。在该模型中，每个模块（Block）在每次调度时消费固定数量的输入采样，并产生固定数量的输出采样。数据流方向严格遵循模块连接顺序：从信源（Source）经过中间处理模块（Processor）流向信宿（Sink）。这种单向、无反馈（除非显式构造）的模型保证了流图的可静态调度性，即调度器可以在运行前预知每个模块的缓冲区需求。

每个模块的 work() 函数接收输入缓冲区指针数组 input_items[] 和输出缓冲区指针数组 output_items[]，并返回实际生产的样本数 n_produced。调度器根据模块声明的 history（历史样本数）和 output_multiple（输出倍数）来保证调用合法性。

关键判断方法：查看模块的 general_work() 或 work() 签名中的 ninput_items[] 数组。如果某个输入端口在调用时收到的样本数少于预期，说明上游模块产出不足，调度器会通过背压机制（Backpressure）限制下游执行，直到缓冲区数据量满足要求。

数据流方向的设计直接影响延迟与吞吐。例如，在 head 模块后接 file_sink 时，数据流被截断；而 delay 模块则引入样本偏移。设计时需注意：流图是静态的，运行时不能动态改变连接关系，但可以通过流标签或消息动态改变模块参数。

4.2 流标签（Stream Tags）：样本的“元数据护照”

核心原理：流标签是附着在特定样本上的键值对（key-value pair），用于携带与采样数据同步的元信息，如帧起始、频率跳变、时间戳、信号功率等。每个标签包含 offset（绝对样本编号）、key（字符串）、value（PMT 类型）和 srcid（来源模块 ID）。标签不占用数据缓冲区空间，而是存储在独立的标签队列中，与采样流并行传播。

标签的传播规则由模块的 propagate_tags() 方法控制。默认情况下，标签会从输入端口传播到所有输出端口，但偏移量会根据模块的消耗/产出比进行换算。例如，一个 2:1 抽取器会将输入标签的 offset 除以 2 后附加到输出样本上。

操作类型	API 方法	典型场景
读取标签	`get_tags_in_range()`	在 work() 中检查当前处理窗口内是否有帧起始标签
写入标签	`add_item_tag()`	检测到信号峰值时打上时间戳标签
删除标签	`delete_tags()`	去除敏感元数据，防止泄漏
标签传播控制	`set_tag_propagation_policy()`	设置为 TPP_DONT 阻止标签传播，或 TPP_ONE_TO_ONE 定向传播

实战经验：在突发通信接收机中，常使用 correlate_access_code_tag_bb 模块检测前导码，并在检测到帧头时打上 packet_len 标签。后续的 pdu_to_tagged_stream 模块会依据该标签自动切分变长数据包，无需外部控制。

常见误区：初学者常混淆标签的 offset 与样本的索引。标签的 offset 是绝对样本编号（从流图启动开始计数），而 work() 中的 nitems_read 是相对当前调用窗口的偏移。必须使用 nitems_read + i 来定位当前处理样本的绝对位置，否则标签会错位。

4.3 消息传递：异步事件与 PDU 通道

核心原理：消息传递机制（Message Passing）用于处理非采样数据，如控制命令、配置参数、以太网帧、FFT 结果等。消息通过模块的 msg_port_out 发射，由 msg_port_in 接收。消息类型为 PMT（Polymorphic Types），支持任意嵌套数据结构。与流标签不同，消息不携带样本偏移，也不受采样率约束，因此适合跨速率域通信。

消息传递有两种模式：直接消息（点对点）和 PDU 消息（包含元数据字典 + 均匀数据向量）。PDU 是流图与外部系统（如 UDP 套接字、ZeroMQ）交互的标准格式。例如，udp_source 模块将接收到的 UDP 包封装为 PDU 消息，通过消息端口输出，而 message_debug 模块可以打印或转发这些消息。

// 在模块构造函数中注册消息端口
message_port_register_out(pmt::mp("pdu_out"));
message_port_register_in(pmt::mp("cmd_in"));
set_msg_handler(pmt::mp("cmd_in"), [this](pmt::pmt_t msg) {
    // 处理命令消息，例如调整增益
    float gain = pmt::to_float(pmt::cdr(msg));
    this->set_gain(gain);
});

操作流程：设计跨域桥接时，推荐使用 msg_connect 方法在 Python 顶层连接消息端口，而非在模块内部硬编码。例如：

tb.msg_connect(fft_block, "pdu_out", qt_sink, "pdu_in")

这种松耦合设计使得模块可复用性大幅提升。注意消息传递是异步的，不保证顺序（除非使用 FIFO 调度），因此在高实时性场景下需谨慎使用。

4.4 流图执行模型：调度器、线程与缓冲区

核心原理：GNU Radio 的调度器（Scheduler）负责决定每个模块何时执行、执行多少次。默认的 thread-per-block 调度器为每个模块分配一个独立线程，模块间通过有界缓冲区（circular buffer）连接。当缓冲区满时，上游线程阻塞；当缓冲区空时，下游线程阻塞。这种模型天然支持流水线并行，但线程切换开销较大。

调度器还支持 single-threaded 模式（通过 tb.set_max_noutput_items() 或 scheduler 配置），适用于低延迟敏感场景。此外，top_block 的 start() 和 wait() 方法控制流图生命周期，而 stop() 用于提前终止。

风险提示：当流图中存在 速率不匹配 的模块（如 1:1 模块后接 1:N 模块）时，调度器可能产生死锁。例如，一个只产生 1 个样本的模块连接到一个要求输入 1024 个样本才能工作的模块，会导致下游永远无法执行。解决方法是插入 throttle 或 keep_one_in_n 模块调整速率。

案例拆解：多速率流图性能调优

假设我们需要设计一个 2.4GHz 频段 20MHz 带宽的 LTE 信号采集器，流图如下：uhd_source → channel_selector（带通滤波+抽取） → fft → qt_gui_sink。初始实现中，FFT 模块的 fft_size=4096，但 GUI 刷新率仅为 30fps，导致 FFT 模块频繁被调度，CPU 占用率高达 85%。

分析过程：通过 top_block 的 dump() 方法查看每个模块的 noutput_items 调用统计，发现 FFT 模块每次仅处理 4096 个样本，但 UHD 源每次产出 8192 个样本。由于缓冲区大小设置不当，调度器频繁切换线程。

优化步骤：

在 UHD 源后插入 head 模块限制样本总数，避免无限采集。
将 FFT 模块的 output_multiple 设置为 4096，确保每次调用处理完整帧。
使用 set_max_noutput_items(8192) 调整 UHD 源的最大产出，减少调度次数。
将 GUI 刷新改为基于消息驱动：FFT 模块通过消息端口发送频谱数据，而非通过采样流。

结果对比：优化后 CPU 占用率降至 32%，GUI 刷新率稳定在 30fps，且无样本丢失。关键收益在于减少了线程上下文切换和缓冲区拷贝次数。

复盘经验：多速率流图的性能瓶颈往往不在算法本身，而在调度器与缓冲区的交互。使用 gr::block::set_output_multiple() 和 set_min_noutput_items() 可以显著改善调度效率。此外，对于周期性数据（如帧），优先使用消息传递而非采样流，可避免缓冲区溢出。

4.5 常见误区与设计复盘

误区一：认为流标签会随采样自动对齐。实际上，如果模块不调用 propagate_tags() 或错误地修改了标签偏移，标签会丢失或错位。务必在自定义模块中显式处理标签传播。
误区二：在 work() 中直接调用 add_item_tag() 时使用相对偏移。必须使用 nitems_written + i 作为 offset。
误区三：忽略消息传递的异步性。当消息用于控制采样流参数时，需通过 try_lock() 或原子操作保护共享状态，否则会产生数据竞争。
误区四：将流图设计为深度流水线（超过 10 级模块）而不考虑线程开销。此时应合并模块或使用 flat_flowgraph 优化。

总结：数据流方向决定了信号处理的逻辑顺序，流标签提供了与样本同步的元数据通道，消息传递则解耦了异步事件，而执行模型决定了系统的实时性与吞吐量。设计者应始终从数据流视角审视流图：哪些数据必须保持采样同步？哪些事件可以异步处理？调度器是否可能成为瓶颈？带着这三个问题，可以快速定位大多数流图设计缺陷。