类型系统

SenRi FFI 提供了一套统一的 C 类型系统，在所有支持的运行时上使用相同的类型名称。

导入

import { types, pointer, array } from 'senri_ffi';

内置类型常量

types 是一个冻结的（Object.freeze）只读对象，包含 13 种基本 C 类型：

types.void      // void — 无返回值
types.int8      // int8_t — 有符号 8 位整数
types.uint8     // uint8_t — 无符号 8 位整数
types.int16     // int16_t — 有符号 16 位整数
types.uint16    // uint16_t — 无符号 16 位整数
types.int32     // int32_t — 有符号 32 位整数
types.uint32    // uint32_t — 无符号 32 位整数
types.int64     // int64_t — 有符号 64 位整数
types.uint64    // uint64_t — 无符号 64 位整数
types.float32   // float — 32 位浮点数
types.float64   // double — 64 位浮点数
types.pointer   // void* — 指针
types.cstring   // char* — C 字符串（以 null 结尾）

类型大小与对齐

类型	大小 (字节)	对齐
void	0	1
int8 / uint8	1	1
int16 / uint16	2	2
int32 / uint32 / float32	4	4
int64 / uint64 / float64	8	8
pointer / cstring	8	8

---

pointer(type?) — 指针类型描述符

创建一个指向指定类型的指针类型描述符。

function pointer(type?: any): any

参数:

• type — 指向的类型。如果不传，默认指向 types.pointer（即 void*）

示例:

pointer(types.int32);        // int32_t*
pointer(types.cstring);      // char**
pointer();                   // void*

// 用在函数绑定中
const func = lib.func(
  'some_func',
  types.void,
  [pointer(types.int32)]   // 接受 int32_t* 参数
);

内部表示:

{ __senri_type: 'pointer', innerType: <type> }

---

array(type, length) — 数组类型描述符

创建一个指定长度和元素类型的数组类型描述符。

function array(type: any, length: number): any

参数:

• type — 元素类型
• length — 数组长度

示例:

array(types.uint8, 256);     // uint8_t[256]
array(types.float64, 16);    // double[16]

// 用在函数绑定中
const func = lib.func(
  'read_bytes',
  types.int32,
  [array(types.uint8, 1024)]  // 接受 uint8_t[1024]
);

内部表示:

{ __senri_type: 'array', innerType: <type>, length: <length> }

---

类型描述符系统

SenRi FFI 内部使用类型描述符标记对象来区分不同的类型类别：

__senri_type	说明
'pointer'	指针类型
'array'	数组类型
'struct'	结构体类型
(无)	原始类型（字符串形式，如 'int32'）

类型规范化流程

当用户传入类型描述符时，normalizeType() 函数负责将其转换为运行时原生类型：

用户类型描述符
    ↓ normalizeType()
        ├─ 原始类型 ('int32') → adapter.mapType() → 运行时类型
        ├─ pointer 描述符     → adapter.createPointerType()
        ├─ array 描述符       → adapter.createArrayType()
        └─ struct 描述符      → adapter.createStructType()
    ↓
运行时原生类型
    ↓
WeakMap 缓存（避免重复转换）

各运行时类型映射

统一类型	KossJS	Bun	Node.js (koffi)
void	'void'	'void'	koffi.void
int8	'int8'	'i8'	koffi.int8
uint8	'uint8'	'u8'	koffi.uint8
int16	'int16'	'i16'	koffi.int16
uint16	'uint16'	'u16'	koffi.uint16
int32	'int32'	'i32'	koffi.int32
uint32	'uint32'	'u32'	koffi.uint32
int64	'int64'	'i64'	koffi.int64
uint64	'uint64'	'u64'	koffi.uint64
float32	'float32'	'f32'	koffi.float
float64	'float64'	'f64'	koffi.double
pointer	'pointer'	'ptr'	koffi.pointer
cstring	'cstring'	'cstring'	koffi.string