# interfaces

**Repository Path**: huyu-project/interfaces

## Basic Information

- **Project Name**: interfaces
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-25
- **Last Updated**: 2026-08-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

---
repo: interfaces
type: open-source
license: MIT
doc_version: v1.3
last_updated: 2026-08-16
---

# interfaces

> Huyu 项目接口注册中心（唯一真相来源）。
> 本仓库开源，包含所有团队间接口定义和接口头文件。
> 各代码仓库通过 CI 拉取本仓库获取编译依赖。

---

## 一、仓库简介

`interfaces` 是 Huyu 项目的接口注册中心，是所有团队间接口的**唯一真相来源**。

本仓库包含：
- `registry.json` - 接口注册中心（机器可读，含冻结状态、预警字段）
- `headers/` - 接口头文件（`.h` / `.hy`），供各代码仓库编译引用
- `headers/common/` - 公共抽象头文件（跨子仓库复用，非接口契约，不参与接口冻结）
  - `slot_manager.h` - `SlotManager<SlotT, N>` 模板：统一槽位管理模式（见下文 §2.5）
- `CHANGELOG.md` - 接口变更日志

---

## 二、接口统计

| 指标 | 值 |
|------|-----|
| 接口总数 | 55 |
| frozen（已冻结） | 34 |
| draft（草稿） | 21 |
| 阶段数 | Phase W |
| 接口状态流 | draft → review → frozen → deprecated |

> **统计说明**（2026-08-16 核实）：registry.json 中注册接口 55 个（34 frozen + 21 draft），headers/ 下对应 58 个主版本文件（46 个 .h + 12 个 .hy）。其中 3 个接口同时有 .h 和 .hy 两个版本文件（T4_BACKEND_HUYU_v1、T4_HY_PROF_v1、T8_CONTAINER_RUNTIME_v1），registry.json 仅引用主版本，配套文件作为附属存在。2 个文件被多接口共享引用：T4_CODEGEN_v1.h 被 T4_CODEGEN_v1/T4_INST_SEL_v1/T4_CALL_CONV_v1 共享，T4_X86_64_BACKEND_v1.h 被 T4_X86_64_BACKEND_v1/T4_X86_INST_v1 共享。

### 2.5 公共抽象（headers/common/，**不参与接口冻结**）

公共抽象是全项目级的"基础设施头文件"，不是团队间契约接口，因此**不在 registry.json 中注册、不参与冻结流程**。
各代码仓库可以自由消费，但如果公共抽象的 API 发生破坏性变更，必须在 `CHANGELOG.md` 记录，并通知所有已接入方。

| 文件 | 公共类型 | 用途 | 已接入模块 |
|------|----------|------|------------|
| `common/slot_manager.h` | `SlotManager<SlotT, N>` 模板 | 统一固定数组槽位管理（`ID = idx + 1`，`allocate / deallocate / at / count / reset / list_ids / for_each`，新增 `allocate_at(idx)` 支持宿主命名空间、指定 ID 分配场景） | ① cgroup（os/kernel/cgroup）<br>② namespace（os/kernel/namespace）<br>③ container runtime（platform/container/runtime）<br>④ gpu（platform/gui/gpu × 4 槽位类型）<br>⑤ linear_scan / graph_coloring（compiler/backend） |
| `common/slot_manager.h` | `HUYU_SLOT_MANAGE(SlotT, N, member)` 宏 | 在模块类中"组合式集成" SlotManager（不引入继承） | 同上 |
| `common/slot_manager.h` | `kInvalidSlotId = 0` 常量 | 统一"无效 ID"语义 | 同上 |

**接入约定（强制）**：
1. `SlotT` 必须包含可公开访问字段 `bool used;`（SlotManager 契约字段），用于编译期约束。
2. 所有分配通过 `allocate()` / `allocate_at()`，释放通过 `deallocate()`，禁止直接修改 `slot.used`（`reset()` / 析构场景除外）。
3. 引入方式：编译参数加 `-I$(HUYU_INTERFACES)/headers`，代码中 `#include "common/slot_manager.h"`。

---

## 三、各仓库消费方式

### 3.1 CI 中拉取

```bash
# 在各代码仓库的 CI 中克隆本仓库
git clone https://gitee.com/huyu-project/interfaces.git /tmp/interfaces

# 编译时指定接口头文件路径
hy-build --include-path /tmp/interfaces/headers
```

### 3.2 Git Submodule（可选）

```bash
# 在代码仓库中添加为 submodule
git submodule add https://gitee.com/huyu-project/interfaces.git interfaces
```

### 3.3 版本锁定

```bash
# 锁定特定版本
git clone --branch v1.0.0 https://gitee.com/huyu-project/interfaces.git
```

---

## 四、接口变更流程

1. 在本仓库发起 PR 修改 `registry.json` 和 `headers/*.h`
2. 项目负责人评审接口变更
3. 合并后由项目负责人更新接口状态（draft → review → frozen）
4. 打 tag 发版（如 `v1.0.0`）
5. 各代码仓库 CI 拉取最新版本

### 接口冻结规则

| 状态 | 含义 | 变更条件 |
|------|------|----------|
| draft | 草稿 | 任意变更 |
| review | 评审中 | 需 PR 评审 |
| frozen | 已冻结 | 仅允许 deprecated，变更需项目负责人批准 |
| deprecated | 已废弃 | 不再使用 |

---

## 五、目录结构

```
interfaces/
├── registry.json          ← 接口注册中心（唯一真相）
├── headers/               ← 接口头文件 + 公共抽象头文件
│   ├── T1_BUILD_SYSTEM_v1.h
│   ├── T2_AST_v1.h
│   ├── T3_HIR_v1.h
│   ├── ...
│   ├── T8_CONTAINER_RUNTIME_v1.hy
│   └── common/            ← 公共抽象头文件（跨子仓库复用，非接口契约）
│       └── slot_manager.h ← SlotManager<SlotT,N> 模板（统一槽位管理模式）
├── CHANGELOG.md           ← 接口变更日志
├── LICENSE                ← MIT 许可证
├── .gitignore
└── README.md              ← 本文档
```

---

## 六、相关文档

- 项目总览：`docs` 仓库 `manager/OVERVIEW.md`
- 仓库架构：`docs` 仓库 `manager/REPO_ARCHITECTURE.md`
- 接口注册中心：本仓库 `registry.json`
- 全局仪表盘：`huyu` 聚合仓库 `DASHBOARD.md`（根目录）