# zr_fast_msg

**Repository Path**: zero-box/zr_fast_msg

## Basic Information

- **Project Name**: zr_fast_msg
- **Description**: Zero-Relay 快速消息队列 - 高性能优先级消息队列库，支持O(1)优先级查找和内存池
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-18
- **Last Updated**: 2026-03-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# zr_fast_msg (Zero-Relay 消息队列)

[English](./README_EN.md)

## 项目简介

zr_fast_msg 是一个高性能的优先级消息队列库，支持 O(1) 复杂度的最高优先级查找，并提供可选的内存池功能以优化内存分配性能。该项目采用纯 C 语言实现，易于集成到各类嵌入式系统和应用程序中。

## 核心特性

- **O(1) 优先级查找**：采用优先级位图技术，快速定位最高优先级消息
- **32 级优先级**：支持从 0（最高）到 31（最低）的优先级划分
- **内存池支持**：可选的内存池模块，减少动态内存分配开销
- **线程安全**：支持自定义锁函数，实现多线程安全操作
- **轻量级**：代码简洁，无外部依赖，适合嵌入式开发

## 目录结构

```
├── zr_msg_queue.h         # 消息队列主头文件
├── zr_msg_queue.c         # 消息队列实现
├── zr_mempool_public.h    # 内存池头文件
├── zr_mempool.c           # 内存池实现
├── zr_msg_def.h           # 基础定义
├── zr_msg_internal.h      # 内部实现
├── zr_msg_queue_public.h  # 公共接口
├── test_zr_msg_queue.c    # 队列测试
├── test_lock_zr_msg_queue.c # 锁函数测试
├── output/
│   ├── markdown/          # Markdown 文档
│   └── web/               # HTML 文档
└── .trae/specs/           # 项目规范文档
```

## 快速开始

### 编译

```bash
# 编译消息队列
gcc -o test_queue test_zr_msg_queue.c zr_msg_queue.c zr_mempool.c -I.

# 编译锁函数测试
gcc -o test_lock test_lock_zr_msg_queue.c zr_msg_queue.c zr_mempool.c -I.
```

### 基本使用示例

```c
#include "zr_msg_queue.h"
#include <stdio.h>

int main() {
    zr_msg_queue_t queue;
    zr_msg_queue_config_t config = {0};
    
    // 初始化队列
    if (zr_msg_queue_init(&queue, &config) != ZR_ERR_OK) {
        printf("队列初始化失败\n");
        return -1;
    }
    
    // 入队消息（优先级 0 最高，31 最低）
    const char *msg1 = "高优先级消息";
    zr_msg_enqueue(&queue, (void*)msg1, 0);
    
    const char *msg2 = "低优先级消息";
    zr_msg_enqueue(&queue, (void*)msg2, 10);
    
    // 出队最高优先级消息
    char *msg = (char*)zr_msg_dequeue_highest(&queue);
    printf("取出消息: %s\n", msg);
    
    // 销毁队列
    zr_msg_queue_deinit(&queue);
    
    return 0;
}
```

### 使用内存池

```c
#include "zr_msg_queue.h"
#include <stdio.h>

int main() {
    zr_msg_queue_t queue;
    zr_mempool_t pool;
    zr_msg_queue_config_t q_config = {0};
    zr_mempool_config_t p_config = {0};
    
    p_config.node_count = 100;  // 预分配节点数量
    
    // 初始化内存池
    zr_mempool_init(&pool, &p_config);
    
    // 初始化队列
    zr_msg_queue_init(&queue, &q_config);
    
    // 绑定内存池到队列
    zr_msg_queue_bind_mempool(&queue, &pool);
    
    // 使用队列（节点从内存池分配）
    zr_msg_enqueue(&queue, "消息1", 5);
    zr_msg_enqueue(&queue, "消息2", 10);
    
    // 出队
    void *msg = zr_msg_dequeue_highest(&queue);
    
    // 解除绑定
    zr_msg_queue_unbind_mempool(&queue);
    
    // 销毁
    zr_msg_queue_deinit(&queue);
    zr_mempool_deinit(&pool);
    
    return 0;
}
```

## API 概览

### 消息队列 API

| 函数 | 描述 |
|------|------|
| `zr_msg_queue_init` | 初始化消息队列 |
| `zr_msg_queue_deinit` | 销毁消息队列 |
| `zr_msg_enqueue` | 消息入队 |
| `zr_msg_dequeue` | 按索引出队 |
| `zr_msg_dequeue_highest` | 最高优先级消息出队 |
| `zr_msg_get_highest_priority_index` | 获取最高优先级索引 |
| `zr_msg_get_by_priority` | 按优先级获取消息索引 |
| `zr_msg_get_status` | 获取队列状态 |
| `zr_msg_get_count_by_priority` | 获取指定优先级消息数量 |
| `zr_msg_queue_bind_mempool` | 绑定内存池 |
| `zr_msg_queue_unbind_mempool` | 解除内存池绑定 |

### 内存池 API

| 函数 | 描述 |
|------|------|
| `zr_mempool_init` | 初始化内存池 |
| `zr_mempool_deinit` | 销毁内存池 |
| `zr_mempool_alloc` | 分配节点 |
| `zr_mempool_free` | 释放节点 |
| `zr_mempool_get_free_count` | 获取空闲节点数量 |

## 优先级说明

| 优先级 | 值 | 说明 |
|--------|-----|------|
| 最高优先级 | 0 |ZR_PRIORITY_HIGHEST |
| 最低优先级 | 31 | ZR_PRIORITY_LOWEST |
| 优先级数量 | 32 | ZR_PRIORITY_MAX |

## 错误码

| 错误码 | 值 | 说明 |
|--------|-----|------|
| ZR_ERR_OK | 0 | 成功 |
| ZR_ERR_FULL | 1 | 队列已满 |
| ZR_ERR_EMPTY | 2 | 队列为空 |
| ZR_ERR_INVALID_PARAM | 3 | 无效参数 |
| ZR_ERR_NO_MEM | 4 | 内存不足 |
| ZR_ERR_NO_MEMPOOL | 5 | 未绑定内存池 |

## 测试

### 运行测试

```bash
# Windows
run_test.bat

# PowerShell
powershell -ExecutionPolicy Bypass -File run_test.ps1
```

### 测试用例

- `test_queue_init` - 队列初始化测试
- `test_enqueue` - 消息入队测试
- `test_highest_priority_index` - O(1) 最高优先级查找测试
- `test_dequeue` - 消息出队测试
- `test_queue_full` - 队列满测试
- `test_queue_empty` - 队列空测试
- `test_get_by_priority` - 按优先级获取索引测试
- `test_mempool` - 内存池测试
- `test_dequeue_highest` - 便捷出队最高优先级测试
- `test_mempool_with_queue` - 内存池配合队列测试
- `test_mempool_bind_and_use` - 内存池绑定队列功能测试
- `test_lock_init` - 锁函数初始化测试
- `test_enqueue_with_lock` - 入队加锁测试
- `test_dequeue_with_lock` - 出队加锁测试

## 文档

详细文档请参考：

- [消息队列使用文档](./output/markdown/msg_queue/usage.md)
- [消息队列 API 文档](./output/markdown/msg_queue/api.md)
- [消息队列架构文档](./output/markdown/msg_queue/architecture.md)
- [内存池使用文档](./output/markdown/mempool/usage.md)
- [内存池 API 文档](./output/markdown/mempool/api.md)
- [内存池架构文档](./output/markdown/mempool/architecture.md)

## 线程安全

项目支持通过自定义锁函数实现线程安全。使用方法：

1. 实现锁函数：
```c
static void* my_mutex_create(void) {
    pthread_mutex_t *mutex = malloc(sizeof(pthread_mutex_t));
    pthread_mutex_init(mutex, NULL);
    return mutex;
}

static void my_mutex_destroy(void *lock) {
    pthread_mutex_destroy((pthread_mutex_t*)lock);
    free(lock);
}

static void my_mutex_lock(void *lock) {
    pthread_mutex_lock((pthread_mutex_t*)lock);
}

static void my_mutex_unlock(void *lock) {
    pthread_mutex_unlock((pthread_mutex_t*)lock);
}
```

2. 在队列配置中传入锁函数：
```c
zr_msg_queue_config_t config = {
    .lock_ops = {
        .create = my_mutex_create,
        .destroy = my_mutex_destroy,
        .lock = my_mutex_lock,
        .unlock = my_mutex_unlock
    }
};
```

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request。