# cxl_shm_lib

**Repository Path**: anolis/cxl_shm_lib

## Basic Information

- **Project Name**: cxl_shm_lib
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 2
- **Created**: 2026-06-02
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CXL 共享内存管理库

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

## 项目概述

基于 C++20 开发的 CXL（Compute Express Link）共享内存管理系统，提供高效的跨进程内存共享能力。项目采用客户端-服务器架构，使用精简版 CacheLib Slab 分配器作为底层内存管理引擎，通过 yalantinglibs coro_rpc 实现高性能进程间通信。

## 核心特性

- **客户端-服务器架构**：Master 服务集中管理内存，客户端通过 RPC 访问
- **引用计数机制**：自动内存回收，支持多进程安全共享
- **消息队列支持**：REQ-RESP（请求-响应）和 PUB-SUB（发布-订阅）两种模式
- **可插拔分配器**：工厂模式支持多种内存分配策略
- **多语言绑定**：提供 C++、C、Python 三种 API
- **高性能优化**：AVX-512 指令支持、分片锁减少竞争
- **监控指标**：内置性能监控和 HTTP 指标服务

## 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                      用户层                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐ │
│  │ C++ Client  │  │ C API       │  │ Python Agent    │ │
│  └─────────────┘  └─────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────┘
                        │ RPC (coro_rpc)
                        ▼
┌─────────────────────────────────────────────────────────┐
│                    Master 服务                           │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐ │
│  │MasterService │  │WrappedMaster │  │ MasterStats   │ │
│  │ (核心逻辑)   │  │Service(RPC)  │  │ (监控指标)    │ │
│  └──────────────┘  └──────────────┘  └───────────────┘ │
└─────────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────┐
│                   内存分配层                             │
│  ┌──────────────────────────────────────────────────┐   │
│  │ BufferAllocatorBase (抽象接口)                    │   │
│  └──────────────────────────────────────────────────┘   │
│        │                                                │
│        ▼                                                │
│  ┌──────────────────────────────────────────────────┐   │
│  │ CachelibBufferAllocator (Slab 分配器)             │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────┐
│                   硬件层                                 │
│  ┌──────────────────────────────────────────────────┐   │
│  │ DAX 设备 (/dev/dax0.0) - CXL 持久内存             │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
```

## 目录结构

```
cxl_share_mem/
├── CMakeLists.txt          # 根目录构建配置
├── dependencies.sh         # 依赖安装脚本
├── cmake/                  # CMake 模块
│   └── FindDependencies.cmake
├── cxl_shm/                # 核心共享内存库
│   ├── include/            # 头文件
│   │   ├── client.h        # C++ 客户端接口
│   │   ├── message_queue.h # 消息队列接口
│   │   ├── master_service.h
│   │   ├── master_proxy.h
│   │   ├── rpc_service.h
│   │   ├── master_stats.h
│   │   ├── types/         # 类型定义
│   │   ├── allocators/    # 分配器接口
│   │   ├── client_capi/   # C 语言 API
│   │   └── utils/         # 工具类
│   └── src/               # 源代码实现
├── cxl_agent/             # Python 绑定模块
├── examples/              # 使用示例
│   └── example.cpp
├── tests/                 # 单元测试
├── extern/                # 外部依赖
│   └── cachelib_allocator/ # 精简版 CacheLib
├── third_party/           # 第三方库 (git submodule)
│   ├── pybind11/          # Python 绑定库
│   └── yalantinglibs/     # RPC/序列化库
└── docs/                  # 文档
    ├── memory_allocator_design.md
    ├── error_handling.md
    └── logging_management.md
```

## 编译与安装

### 前提条件

- CMake 3.16+
- C++20 兼容编译器 (GCC 10+, Clang 10+)
- Python 3.6+ (可选，用于 Python 绑定)

### 编译步骤

```bash
# 1. 克隆项目（包含子模块）
git clone --recursive <repository-url>
cd cxl_share_mem

# 2. 安装依赖
./dependencies.sh

# 3. 创建构建目录
mkdir build && cd build

# 4. 配置 CMake
cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local

# 5. 编译
make -j$(nproc)

# 6. 安装
sudo make install

# 7. 刷新动态链接器缓存（必须，否则运行时找不到 libcxl_shm_lib.so）
sudo ldconfig
```

### 编译选项

| 选项 | 默认值 | 说明 |
|-----|--------|------|
| `BUILD_UNIT_TESTS` | ON | 构建单元测试 |
| `USE_AVX_512` | OFF | 启用 AVX-512 指令优化 |
| `USE_AVX_2` | OFF | 启用 AVX-2 指令优化 |
| `ENABLE_ASAN` | OFF | 启用地址检测器 |
| `USE_CACHELIB` | ON | 使用 CacheLib 分配器 |

示例：
```bash
cmake .. -DUSE_AVX_512=ON -DBUILD_UNIT_TESTS=OFF
```

## 使用方法

### 1. 启动 Master 服务

```bash
cxl_shm_master --dev_dax_path=/dev/dax0.0 --dev_dax_size=4294967296 --rpc_port=50051
```

参数说明：
- `--dev_dax_path`: DAX 设备路径（默认 `/dev/dax0.0`）
- `--dev_dax_size`: DAX 设备大小（字节，默认 4GB）
- `--rpc_port`: RPC 服务端口（默认 50051）

### 2. C++ API

#### 基础内存操作

```cpp
#include <iostream>
#include <cxl_shm/client.h>

int main() {
    // 创建客户端
    auto client_result = cxl_shm::Client::Create(true, "my_client", "localhost:50051");
    if (!client_result) {
        std::cerr << "Failed to create client: " << cxl_shm::toString(client_result.error()) << std::endl;
        return 1;
    }
    auto client = client_result.value();
    
    // 分配内存
    auto result = client->Malloc("my_object", 2097152);  // 2MB
    if (!result) {
        std::cerr << "Failed to allocate: " << cxl_shm::toString(result.error()) << std::endl;
        return 1;
    }
    
    auto buffer = result.value();
    std::cout << "Allocated: " << buffer.name_ << ", size: " << buffer.size_ << std::endl;
    
    // 获取内存引用
    auto get_result = client->Get("my_object");
    if (get_result) {
        auto get_buffer = get_result.value();
        // 读写 get_buffer.buffer_ 指向的内存
    }
    
    // 释放引用（引用计数 -1，为 0 时自动释放内存）
    client->Release("my_object");
    
    return 0;
}
```

#### 消息队列操作

```cpp
#include <cxl_shm/message_queue.h>

// 服务端
auto channel_result = cxl_shm::Channel::Create(true, "server", "localhost:50051");
auto channel = channel_result.value();
channel->Register(cxl_shm::ChannelMode::REQ, "my_topic", 1024, 64);  // REQ 模式

// 等待客户端消息
cxl_shm::TopicDescriptor desc;
channel->Recv("my_topic", desc, buffer, size);
channel->Send("my_topic", desc, response, response_size);

// 客户端
auto channel_result = cxl_shm::Channel::Create(false, "client", "localhost:50051");
auto channel = channel_result.value();
channel->Bind(cxl_shm::ChannelMode::REQ, "my_topic");
channel->Send("my_topic", request, request_size);
channel->Recv("my_topic", desc, buffer, size);
```

### 3. C 语言 API

```c
#include <cxl_shm/client_capi/cxl_shm_client_c.h>
#include <cxl_shm/client_capi/cxl_mq_client_c.h>

// 共享内存操作
cxl_shm_client_t client;
cxl_shm_client_init(&client, "my_client", "localhost:50051");

cxl_object_buff_t buf;
int ret = cxl_shm_malloc(&client, "my_object", 2048, &buf);
// 使用 buf.buffer...

cxl_shm_rel(&client, "my_object");
cxl_shm_client_exit(&client);

// 消息队列操作
cxl_channel_t channel;
cxl_channel_create(&channel, false, "client", "localhost:50051");
cxl_channel_bind(&channel, CXL_CHANNEL_MODE_REQ, "my_topic");
cxl_channel_send(&channel, "my_topic", data, size);
cxl_channel_recv(&channel, "my_topic", buffer, &size);
cxl_channel_destroy(&channel);
```

### 4. Python API

```python
import cxl_agent

# 创建 Agent
agent = cxl_agent.CxlAgent()
agent.setup(is_server=True, client_name="server", rpc_addr="localhost:50051")

# 内存操作
agent.malloc("my_object", 2048)
buf = agent.get("my_object")
agent.release("my_object")

# 消息队列
channel = agent.create_channel("my_channel")
channel.register(cxl_agent.ChannelMode.REQ, "topic", 1024, 64)
channel.send_message("topic", "Hello")
msg = channel.recv_message("topic")
```

## 核心 API

### Client 类（C++）

| 方法 | 说明 |
|-----|------|
| `Create(is_server, name, addr)` | 创建客户端实例 |
| `Malloc(key, size)` | 分配共享内存 |
| `Free(key)` | 释放共享内存 |
| `Get(key)` | 获取内存引用（引用计数 +1） |
| `Release(key)` | 释放引用（引用计数 -1） |
| `PutData(key, size, data)` | 分配内存并写入数据 |
| `GetData(key, data)` | 读取内存数据 |
| `Lock(key)` | 锁定内存对象 |
| `Unlock(key)` | 解锁内存对象 |

### Channel 类（C++）

| 方法 | 说明 |
|-----|------|
| `Create(is_server, name, addr)` | 创建通道实例 |
| `Register(mode, topic, msg_size, msg_num)` | 注册主题（服务端） |
| `Unregister(topic)` | 注销主题（服务端） |
| `Bind(mode, topic)` | 绑定主题（客户端） |
| `Unbind(mode, topic)` | 解绑主题（客户端） |
| `Send(topic, data, size)` | 发送消息 |
| `Recv(topic, desc, buf, size)` | 接收消息 |

### 消息队列模式

- **REQ (Request-Response)**: 请求-响应模式，点对点通信
- **PUB (Publish-Subscribe)**: (TODO) 发布-订阅模式，支持多订阅者

## 安装产物

安装完成后，文件位置：

```
/usr/local/
├── bin/
│   └── cxl_shm_master       # Master 服务
└── lib/
    └── libcxl_shm_lib.so    # 共享库

/usr/local/include/cxl_shm/
├── client.h
├── message_queue.h
├── types/
│   ├── base_types.h
│   ├── object_types.h
│   ├── mq_types.h
│   └── error_types.h
├── allocators/
│   ├── allocator.h
│   └── allocator_factory.h
├── client_capi/
│   ├── cxl_shm_client_c.h
│   └── cxl_mq_client_c.h
└── utils/
    └── ...
```

## 编译应用程序

```cmake
cmake_minimum_required(VERSION 3.16)
project(myapp VERSION 1.0.0 LANGUAGES CXX C)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

include_directories(SYSTEM /usr/local/include/cxl_shm)
link_directories(/usr/local/lib)

find_package(Threads REQUIRED)

add_executable(myapp myapp.cpp)

target_link_libraries(myapp PRIVATE
    cxl_shm_lib
    Threads::Threads
)
```

## 监控指标

Master 服务内置 HTTP 监控端点（端口 8080）：

```
# 获取指标
curl http://localhost:8080/metrics
```

指标包括：
- 内存使用量、容量、对象数量
- 活跃客户端数
- 操作计数（malloc/free/get/release 等）

## 注意事项

1. 确保 CXL 设备已正确配置和挂载
2. 应用程序需要适当权限访问 DAX 设备
3. 多进程访问同一内存需自行处理同步
4. 使用引用计数机制确保内存安全释放

## 依赖库

| 库 | 版本 | 说明 |
|---|------|------|
| glog | v0.7.1 | 日志库 |
| yalantinglibs | 0.5.1 | RPC/序列化库 |
| pybind11 | stable | Python 绑定 |
| Boost | - | UUID 生成 |
| folly (精简版) | - | 工具库 |

## 许可证

本项目采用 [Apache-2.0](LICENSE) 许可证开源。

## 贡献指南

欢迎贡献代码！请提交 Pull Request。