Library

Library 类用于加载原生共享库并绑定 C 函数。

导入

import { Library } from 'senri_ffi';

静态方法

Library.load(path: string): Library

加载指定路径的原生共享库，返回一个 Library 实例。

const lib = Library.load(
  process.platform === 'win32' ? 'user32.dll' : 'libm.so.6'
);

参数:

• path — 共享库的文件路径（Windows: .dll、Linux: .so、macOS: .dylib）

返回值: Library 实例

各运行时实现:

运行时	实现
KossJS	_senri_ffi.open(path)
Bun	Bun.ffi.dlopen(path, {})
Node.js	koffi.load(path)

错误: 加载失败时抛出 FFIError

---

实例方法

func(name, retType, argTypes[], options?): Function

绑定一个 C 函数，返回可调用的 JavaScript 函数。结果会被缓存，对同一签名重复调用返回相同的函数对象。

const abs = lib.func('abs', types.int32, [types.int32]);
console.log(abs(-42)); // 42

参数:

参数	类型	说明
name	string	C 函数名称
retType	类型描述符	返回值类型
argTypes	类型描述符数组	参数类型列表
options	object?	可选配置（运行时特定）

缓存机制:

内部使用 Map<string, Function> 缓存已绑定的函数，缓存键为：

name + '|' + JSON.stringify(retType) + '|' + JSON.stringify(argTypes)

这意味着对相同名称和签名的函数，多次调用 func() 不会重复绑定，直接返回缓存结果。

// 第二次调用直接返回缓存
const fn1 = lib.func('abs', types.int32, [types.int32]);
const fn2 = lib.func('abs', types.int32, [types.int32]);
console.log(fn1 === fn2); // true

---

close(): void

关闭库并释放资源。关闭后不能再调用 func()。

lib.close();

行为:

• 清空函数缓存 (_funcCache.clear())
• 释放库句柄（取决于运行时实现）
• 设置 _closed = true
• 重复调用 close() 不会报错（幂等）

各运行时实现:

运行时	实现
KossJS	handle.close()
Bun	置空内部引用 (__lib = null)
Node.js	空操作（koffi 自动管理生命周期）

---

完整示例

import { Library, types } from 'senri_ffi';

const lib = Library.load(
  process.platform === 'win32' ? 'user32.dll' : 'libm.so.6'
);

// 绑定多个函数
const abs = lib.func('abs', types.int32, [types.int32]);
const sqrt = lib.func('sqrt', types.float64, [types.float64]);

console.log(abs(-100));   // 100
console.log(sqrt(25));    // 5

// 关闭库
lib.close();

// 关闭后调用会抛出 FFIError
// lib.func('abs', types.int32, [types.int32]); // 抛出错误