LSR 003 - Lamina C 扩展与插件规范¶
基本信息¶
LSR 编号 003
标题 Lamina C 扩展与插件规范
作者 Ziyang-Bai
状态 草案
类型 标准规范
创建日期 02-04-2026
归属项目 编译器、虚拟机、包管理器
摘要¶
定义 C/C++ 扩展的最小交付、接口映射与内存/所有权约束。
技术规范¶
1. 最小交付物¶
最小交付：
动态库项目（可编译生成
.dll/.so/.dylib）Lamina 模块声明文件（默认文件名
lib.lm）
推荐目录（非强制）：
[root]/lib.lm[root]/src/[root]/include/（可选）
2. 元数据文件（可选）¶
lampm.json 可选，用于补充包管理与自动构建信息；接口绑定前置条件仅为动态库与 lib.lm。
若提供 lampm.json，建议字段如下：
字段 |
类型 |
说明 |
|---|---|---|
|
String |
包名 |
|
String |
建议为 |
|
String |
C/C++ 标准版本 |
|
Array |
编译参数 |
|
Array |
链接库列表 |
|
String |
接口文件路径，默认 |
|
String |
动态库入口函数名，默认 |
未提供 lampm.json 时，工具链按默认约定加载：
接口文件：
lib.lm入口符号：
lsr_init动态库名称：由构建系统决定
3. 接口映射语法（必需）¶
在 lib.lm 中使用 module 声明扩展命名空间，函数签名遵循 LSR-000：
静态强类型
参数与返回类型必须显式
类型标注语法采用
name Type
module example {
# 语法：func name(param Type, ...) -> ReturnType = "c_symbol"
func det(m matrix) -> num = "c_ext_det"
func eig(m matrix) -> matrix = "c_ext_eig"
}
3.1 table 类型接口约束¶
当接口参数或返回值使用 table<K, V> 时，必须满足：
K必须可哈希默认允许键类型：
num、complex、text、bool默认键类型范围仅包含：
num、complex、text、bool其他类型作为键需显式声明哈希语义（如
vector、matrix、set、table）
违反约束时接口绑定报错并停止生成桥接代码。
module ext_table {
func score_of(t table<text, num>, name text) -> num = "c_ext_score_of"
# 示例：vector 作为键需显式哈希语义
# func bad(t table<vector, num>) -> num = "c_ext_bad"
}
3.2 复合对象内存安全与所有权协议¶
复合对象参数必须声明访问模式：
@readonly：只读视图；原地写入需先clone_if_shared@move：所有权转移，扩展接管生命周期
默认 @readonly。
3.2.1 引用计数约束¶
@readonly绑定必须增加持有计数，释放时归还@move绑定后 Lamina 侧引用失效，生命周期转移到扩展扩展持有指针需显式声明所有权
3.2.2 写入前克隆要求¶
在 @readonly 模式下，如需写入，必须调用运行时接口：
clone_if_shared(obj)
独占对象：直接返回可写对象
共享对象：先复制再返回可写对象
共享对象写入前必须调用该接口；运行时对未调用写入触发 ExtensionMutationViolation。
3.2.3 接口示例¶
module ext_safe {
func frobenius(a matrix @readonly) -> num = "c_ext_frob"
func consume(t table<text, num> @move) -> bool = "c_ext_consume"
}
规则：@readonly / @move 为接口注解。未声明时默认 @readonly。
4. 错误与诊断¶
至少支持：
InterfaceBindError：接口映射失败TableKeyTypeError：table键类型不合法OwnershipViolation：所有权协议违规ExtensionMutationViolation：未按规则写共享对象
5. 与其他 LSR 的关系¶
LSR-000：核心类型系统、值语义、COW 语义
LSR-004：标准库定义，扩展可作为补充实现
LSR-008：量纲剥离规则（扩展无量纲入参场景）
