# raptor

**Repository Path**: shadowyuan/raptor

## Basic Information

- **Project Name**: raptor
- **Description**: TCP Network Library Implementation (C++)
- **Primary Language**: C++
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 13
- **Forks**: 2
- **Created**: 2021-03-09
- **Last Updated**: 2026-06-28

## Categories & Tags

**Categories**: web-dev-toolkits

**Tags**: None

## README

# [raptor-lite](https://gitee.com/shadowyuan/raptor-lite)


`raptor-lite` 是一个使用 C++ 封装实现的 TCP 网络库，内部有 EPOLL(Linux) 和 IOCP(Windows) 两套实现，调用接口 (API) 采用委托服务和事件接口的设计方式。

## 使用方法

### CMake 编译

需要 CMake 版本等于或高于 3.13。我们需要让 CMake 生成的文件与项目文件在不同的目录中，因此，建立一个 `build` 目录并在其中运行 CMake。

```c
  mkdir build
  cd build
  cmake .. -DCMAKE_BUILD_TYPE=Release
```

如果在 Unix 平台，接下来就可以直接使用 `make` 命令进行编译了：

```c
  make
```

如果在 Windows 平台，需要安装 Visual Studio。推荐使用 Visual Studio 2015 之后的版本。在使用 `cmake` 命令时可以加上 `-G` 参数指定 Visutal Studio 版本。

```sh
  cmake .. -G "Visual Studio 15 2017"
```

或指定 64 位版本

```sh
  cmake .. -G "Visual Studio 15 2017 Win64"
```

编译命令：

```sh
  cmake --build . --config Release
```

### 安装

完成前面的编译操作之后，如果是 Unix 系统，可以直接 `make install` 安装头文件与 Lib(libraptor-lite.lib) 文件。在 Windows 系统则需要手将动将 `include` 目录和生成的 `raptor-lite.lib` 文件拷贝到你需要的目录。

### 头文件包含与静态库链接

在源码中头文件包含代码如下：

```c
  #include <raptor-lite/raptor-lite.h>
```

在 Windows 平台使用 Visual Studio 需要在项目属性中找到 `链接器->输入->附加依赖项` 然后加上 raptor-lite.lib，或者在源码中加上以下代码链接：
```c
  #pragma comment(lib, "raptor-lite.lib")
```

在 Unix 平台则需要在 `Makefile` 中使用 `-L` 指定库的目录，并添加 `-lraptor-lite` 链接。


## 示例

### Example 1：客户端连接目标服务器
```c++
// 实现 ConnectorHandler
class ClientHandler : public raptor::ConnectorHandler {
public:
    ClientHandler(/* args */) {}
    ~ClientHandler() {}

    void OnConnectFailed(intptr_t user, raptor_error desc) {
        log_warn("OnConnectFailed: %lld", user);
    }

    void OnConnect(raptor::Endpoint ep, raptor::Property &settings) {
        log_debug("OnConnect: %lld", ep.SocketFd());
        settings({raptor::config::kSocketRecvTimeoutMs, 5000});
        settings({raptor::config::kSocketSendTimeoutMs, 5000});
        settings({raptor::config::kSocketNonBlocking, false});
    }
};

ClientHandler handler;
raptor::Connector *connector = nullptr;
RaptorEngine engine = RaptorCreateEngine();

// 设置 property
raptor::Property p(
    {raptor::config::kConnectorHandler, static_cast<raptor::ConnectorHandler *>(&handler)}
);

// 创建 connector
engine->CreateConnector(p, &connector);

// 运行 connector
connector->Start();

// 连接目标服务器, 参数 ipv4: ip:port, ipv6: [ip]:port
connector->Connect("0.0.0.0:9527");

// 最后连接成功或失败均会通过 ClientHandler 通知你
// 在 OnConnectFailed 中可以查看错误描述
// 在 OnConnect 中可以设置 socket 连接的相关属性

```

### Example 2：服务端监听连接
```c++
// 与上一个例子类似，需要实现 raptor::AcceptorHandler
class ServerHandler : public raptor::AcceptorHandler {
public:
    ServerHandler(/* args */) {}
    ~ServerHandler() {}

    void OnAccept(raptor::Endpoint ep, raptor::Property &settings) {
        settings({raptor::config::kSocketRecvTimeoutMs, 5000});
        settings({raptor::config::kSocketSendTimeoutMs, 5000});
    }
};

ServerHandler handler;
raptor::Acceptor *acceptor = nullptr;
RaptorEngine engine = RaptorCreateEngine();

// 设置 property
raptor::Property p(
    {raptor::config::kAcceptorHandler, static_cast<raptor::AcceptorHandler *>(&handler)}
);

// 创建 acceptor
engine->CreateAcceptor(p, &acceptor);

// 运行 acceptor
acceptor->Start();

// 添加监听地址, 参数 ipv4: ip:port, ipv6: [ip]:port
acceptor->AddListening("0.0.0.0:9527");

// 最后监听的客户端连接会 AcceptorHandler 通知你

```

### Example 3：连接的数据收发与管理
```c++
// 通过前面两个示例已经可以完成连接创建，接下来需要实现数据数据收发
// 使用的对象是 raptor::Container
class ServerHandler :  public raptor::AcceptorHandler,
                       public raptor::MessageHandler,
                       public raptor::ProtocolHandler {
public:
    int OnCheckPackageLength(raptor::Endpoint ep, const void *data, size_t len) {
        // 数据包长度解析
        return static_cast<int>(len);
    }

    void OnMessage(raptor::Endpoint ep, const raptor::Slice &msg) {
        // Message process
    }
};

// 创建 container
ServerHandler handler;
raptor::Property p{
    {raptor::config::kAcceptorHandler, static_cast<raptor::AcceptorHandler *>(&handler)},
    {raptor::config::kMessageHandler, static_cast<raptor::MessageHandler *>(&handler)},
    {raptor::config::kProtocolHandler, static_cast<raptor::ProtocolHandler *>(&handler)},
    {raptor::config::kCheckReceivingInterval, false},
    {raptor::config::kRecvSendThreads, 2}
};

raptor::Container *container = nullptr;
RaptorEngine engine = RaptorCreateEngine();

engine->CreateContainer(p, &container);
container->Start();

// 从 OnConnect & OnAccept 中得到的 socket 连接与 container 绑定
// 此后即可从各种 Handler 的实现函数中获得各种事件通知
container->AttachEndpoint(ep);

```

综合上述，可知 `raptor-lite` 库有一个引擎组件 `Engine`，通过该组件可以创建 `Connector`、`Acceptor` 以及 `Container` 三个组件。通过对它们的组合使用，可以轻松实现 Tcp 客户端、Tcp 服务端 或是 Tcp 网关。更详细的示例代码请查阅 `example` 目录中的源码。

## 其他

1. 示例中出现的几种 Handler，详情请查看 [property](doc/property.md)。

2. 要实现网关可以创建两个 `RaptorEngine` 对象，但是两个 `Engine` 对象的 `Endpoint` 切勿交叉使用。

3. 如果您有什么问题反馈，请联系我（shadow_yuan@qq.com）。