【Qt】 QSerialPort::flush()介绍

Qt串口 flush() 核心速览

QSerialPort::flush() 是非阻塞、尽力发送 函数：将串口内部输出缓冲区的数据，尽可能立即写入底层串口驱动/硬件，不等待发送完成、不阻塞线程。

一、函数定义与返回值

bool QSerialPort::flush();

• 返回 true：成功将部分/全部缓冲数据写入底层驱动（不代表已从硬件发出）
• 返回 false：串口未打开、无数据可刷、或底层写入失败

二、核心原理与行为

1. 数据流向 ：write() → Qt内部输出缓冲区 → flush() → 系统串口驱动缓冲区 → 硬件发送
2. 非阻塞特性 ：调用后立即返回，不等待数据完全发送到对端，也不等待硬件发送完成
3. 自动发送机制 ：正常带事件循环的Qt程序，write()后数据会在事件循环空闲时自动发送 ，通常不需要手动flush
4. 平台差异 ：仅操作输出缓冲区（发送方向） ，不清理输入缓冲区；底层依赖系统串口驱动实现，不同系统（Windows/Linux/macOS）表现略有差异

三、适用场景（什么时候必须用）

• 无事件循环/阻塞线程（如子线程、控制台程序），write()后数据不会自动发送，必须手动flush()
• 发送短指令/实时控制帧，要求数据尽快发出、不等待事件循环调度
• 串口即将关闭/程序退出前，确保残留缓冲数据被送出（但不能保证完全发完）

四、常见误区（重点避坑）

❌ 误区1：flush()="数据已全部发送完成"

✅ 真相：flush()只负责把Qt内部缓冲推给驱动，不保证驱动已发完、硬件已送出、对端已收到 ；要确保发送完成，必须用 waitForBytesWritten(超时) 或监听 bytesWritten() 信号

❌ 误区2：flush()会清空接收缓冲区

✅ 真相：flush()只处理输出（发送） ；要清输入缓冲，用 clear(QSerialPort::Input)

❌ 误区3：每次write()都必须flush()

✅ 真相：带事件循环的GUI程序，自动发送足够高效；频繁flush()反而增加系统调用开销

五、正确用法示例

#include <QSerialPort>

QSerialPort serial;
serial.setPortName("COM3");
serial.setBaudRate(QSerialPort::Baud115200);
if (serial.open(QIODevice::ReadWrite)) {
    // 写入数据到内部缓冲区
    serial.write("AT+RST\r\n");
    // 非阻塞，尽快推送到驱动
    serial.flush();
    
    // ✅ 若要确保数据完全发送（必须）：
    if (!serial.waitForBytesWritten(100)) { // 超时100ms
        qDebug() << "发送超时：" << serial.errorString();
    }
}

六、与相关函数对比

函数	作用	阻塞	方向	保证发送完成
flush()	尽力推送内部输出缓冲到驱动	非阻塞	仅输出	❌ 不保证
waitForBytesWritten(ms)	阻塞等待指定字节发送完成	阻塞	输出	✅ 保证
clear(Directions)	清空输入/输出缓冲	非阻塞	输入/输出	-
bytesWritten()	信号：通知已发送字节数	异步	输出	✅ 通知

七、总结

flush()是快速推送缓冲、不等待、不保证完成 的辅助函数；仅在无事件循环、实时短帧、关闭前等场景使用；确保数据可靠发送，必须搭配 waitForBytesWritten() 或 bytesWritten() 信号。