diff --git a/README.md b/README.md index cb8fe82ca0cd7d47d46900f3c463ac9439e91806..9b8def1c4f5ebc042d97510fa63349fb11914961 100644 --- a/README.md +++ b/README.md @@ -1,112 +1,113 @@ + + # QtTcpMultithreading -#### 介绍 -基于Qt开发的多线程tcp,可以在多线程安全使用 +## 介绍 +QtTcpMultithreading 是一个基于 Qt 框架实现的 TCP 多线程通信库,旨在为用户提供简单、高效的 TCP 通信解决方案。该项目支持客户端和服务器端的通信,并通过多线程或任务池机制优化了数据传输性能,确保在高并发场景下仍能稳定运行。 -#### 软件架构 -软件架构说明 +该项目适合用于需要高性能 TCP 通信的 C++ 应用程序,例如分布式系统、网络服务器和客户端程序。 +## 软件架构 +该库主要由以下组件构成: -#### 安装教程 +- **TcpClient_T** 和 **TcpClient_T_Private**:负责 TCP 客户端功能,包括连接、数据读写、多线程支持。 +- **TcpServer_T**:负责 TCP 服务器的连接管理,支持新连接的接收。 +- **测试模块(test)**:包含多个测试项目,用于验证客户端和服务器的功能,以及展示如何使用库。 -1. 需要已经安装Qt,测试版本为Qt5.15.2; +整个项目使用 Qt 的网络模块(QtNetwork)和多线程支持(QtConcurrent),确保在多线程环境下安全地进行网络通信。 -2. 在环境变量中加入Qt的bin路径(qmake.exe所在路径); +## 安装教程 -3. OPTION CompileTest 默认为ON,如果不需要编译,需要设置为OFF,在CPM中使用如下: +### 先加入组件 +在使用该项目前,请确保你的开发环境已安装以下组件: +- Qt5 或更高版本 +- CMake(用于构建) +- 支持 C++11 或更高版本的编译器 - ```cmake - # 先加入组件 - include(CPM) - - # 拉去并使用库 - CPMAddPackage( - # 库命名 - NAME QtTcpMultithreading - # 库的地址 - GIT_REPOSITORY ssh://git@192.168.101.129:3022/libs/cpplibs/QtTcpMultithreading.git - # 库的tag标签或者分支名字 - GIT_TAG v0.1 - # 设置options - OPTIONS "CompileTest OFF" - ) - +### 拉取并使用库 +1. 从 Gitee 拉取项目: + ```bash + git clone https://gitee.com/Coder_Zr/QtTcpMultithreading.git + ``` +2. 构建项目: + ```bash + cd QtTcpMultithreading + mkdir build && cd build + cmake .. + make ``` - - -#### 使用说明 - -##### tcp server使用: - -```c++ -#include "QtTcpMultithreading.h" - -// 用于记录新连接的socket -ZTcp::TcpClient_T *client_{nullptr}; - -// 用于新链接的socket收到信息时,进行处理的逻辑函数,替换为你的代码 -void MainWindow::dealRead(const QByteArray &arg) { - qDebug() << "receive:" << arg; - static int num{0}; - QtConcurrent::run([=] { - for (int i{0}; i != 10; ++i) { - QByteArray msg{QString{"%1:%2"}.arg(num++).arg("world").toUtf8()}; - // 多线程中调用socket,可以在任意地方调用 - client_->write("world"); - } - }); -} - -void MainWindow::on_btnTest0_clicked() { - // 初始化 server - ZTcp::TcpServer_T *server{new ZTcp::TcpServer_T{this}}; - // 监听地址、端口 - server->listen(QHostAddress{"127.0.0.1"}, 9966); - // 当有新的请求连接时,触发sigNewClient信号 - connect(server, &ZTcp::TcpServer_T::sigNewClient, [=](ZTcp::TcpClient_T *client) { - // 可以记录下来,在其他多线程中调用 - client_ = client; - // 使用read注册回调函数dealRead - client_->read([this](auto &&arg) { dealRead(std::forward(arg)); }); - }); -} +### 库命名 +该库的命名空间为 `ZTcp`,主要类包括 `TcpClient_T` 和 `TcpServer_T`。 -``` +### 库的地址 +库地址:[https://gitee.com/Coder_Zr/QtTcpMultithreading](https://gitee.com/Coder_Zr/QtTcpMultithreading) + +### 库的 tag 标签或者分支名字 +默认使用 `master` 分支,具体 tag 请查看项目版本发布。 -##### tcp client使用: - -```c++ -#include "QtTcpMultithreading.h" - -// 用于记录连接的socket -ZTcp::TcpClient_T *client_{nullptr}; - -void MainWindow::on_btnTest0_clicked() { - // 准备回复的消息 - QString msg{"myTest"}; - // 实例化client - client_ = new ZTcp::TcpClient_T{this}; - - // 绑定client自身的ip和端口 - // client_->bind(QHostAddress{"127.0.0.1"},18899); - - // 设置读取到消息时的处理函数 - client_->read([](QByteArray msg) { - qDebug() << "client receive:" << msg; - }); - - // 连接到server - client_->connectToHost(QHostAddress{"127.0.0.1"}, 9966); - // 启动 - client_->start(); -} - -void MainWindow::on_btnTest1_clicked() { - // 使用记录的client在多线程发送消息 - QtConcurrent::run([=]{ - client_->write("client hello"); - }); -} +### 设置 options +在使用 `TcpClient_T` 时,可以通过构造函数设置是否启用任务池: +```cpp +TcpClient_T(QObject *parent, bool useTaskPool = false, qintptr socketDescriptor = -1) ``` +## 使用说明 + +### TCP Server 使用 +1. 引入库: + ```cpp + #include "QtTcpMultithreading.h" + ``` +2. 创建服务器对象: + ```cpp + TcpServer_T server; + server.listen(QHostAddress::Any, 8080); + ``` +3. 处理新连接和数据: + ```cpp + connect(&server, &TcpServer_T::newConnection, this, &MainWindow::dealNewConnection); + ``` + +### TCP Client 使用 +1. 引入库: + ```cpp + #include "QtTcpMultithreading.h" + ``` +2. 创建客户端并连接: + ```cpp + TcpClient_T client; + client.connectToHost(QHostAddress("127.0.0.1"), 8080); + client.start(); + ``` +3. 读写数据: + - 同步读: + ```cpp + client.read([](const QByteArray &data) { + // 处理数据 + }); + ``` + - 异步写: + ```cpp + client.writeAsync("Hello Server"); + ``` + +## 示例项目 +项目包含多个测试示例,展示了客户端和服务器的基本使用方法: +- **QtTcpMultithreadingClient**:TCP 客户端测试界面 +- **QtTcpMultithreadingServer**:TCP 服务器测试界面 +- **QtTcpMultithreadingTest0**:展示 lambda 函数和数据处理的示例 + +## 贡献指南 +欢迎贡献代码!请遵循以下步骤: +1. Fork 项目。 +2. 创建新分支 (`git checkout -b feature/your-feature-name`)。 +3. 提交更改 (`git commit -am 'Add some feature'`). +4. Push 到分支 (`git push origin feature/your-feature-name`). +5. 提交 Pull Request。 + +## 许可协议 +该项目遵循 MIT 许可协议。详情请查看 `LICENSE` 文件。 + +## 致谢 +感谢 Qt 提供的网络模块和并发支持,使得实现多线程 TCP 通信变得更加简单。 \ No newline at end of file