Public C11 API

把 LNS 嵌入你的宿主程序。

公开 API 面向设备、网关、游戏和自动化工具的宿主开发者。你控制内存、能力和模块来源，LNS 负责执行用户脚本。

C11纯 ISO C11 头文件，不依赖操作系统线程或 C++ 运行时。
Controlled资源限制和明确的 VM 生命周期控制执行边界。
Budgeted内存、栈、调用深度和指令预算都可以由宿主限制。
Lua-style栈式 VM 设计让执行、暂停和恢复保持简单。

最短接入流程

头文件位于 `interpreter-api/include`，通常只需要包含 `lnscript.h`。源码和字节码运行共享同一套资源限制、错误处理和生命周期规则。

  1. 初始化 `ln_config`、分配器和资源上限。
  2. 创建 `ln_vm`。
  3. 运行源码或已校验字节码。
  4. 读取错误和结果，释放 VM。
#include <stdlib.h>

static void *host_alloc(void *ctx, void *old_ptr,
                        size_t old_size, size_t new_size) {
  (void)ctx; (void)old_size;
  return realloc(old_ptr, new_size);
}

static void host_free(void *ctx, void *ptr, size_t size) {
  (void)ctx; (void)size;
  free(ptr);
}

ln_config config;
ln_vm *vm = NULL;
ln_chunk *chunk = NULL;
ln_status status;

ln_config_init(&config);
config.limits.memory_limit = 64u * 1024u;
config.limits.value_stack_limit = 2048u;
config.allocator.alloc = host_alloc;
config.allocator.free = host_free;

status = ln_vm_new(&config, &vm);
if (status == LN_STATUS_OK) {
  status = ln_compile(vm, &source, &chunk);
}
if (status == LN_STATUS_OK) {
  status = ln_vm_execute_with(vm, chunk, &options);
}

ln_chunk_free(vm, chunk);
ln_vm_free(vm);

两种运行入口

ln_vm_run_rawcode

接收 LNS 源码，内部完成编译和执行。适合开发阶段、配置脚本和启动脚本。

ln_vm_run_state state;
ln_vm_run_rawcode(vm, &source, &options, &state);

ln_vm_run_bytecode

接收 `.lnbc` 字节码，先校验 LNSC magic、版本、段、opcode、索引和资源限制，再执行。

ln_bytecode bytecode = {
  bytes, length, "cached.lnsc"
};
ln_vm_run_bytecode(vm, &bytecode, &options, &state);

Value、handle 与宿主生命周期

Value

`ln_value` 是宿主和 VM 之间的固定大小值。字符串、table、function 和 handle 的内部对象不对宿主开放。

Root

宿主需要跨越一次 API 调用保存 VM 值时，使用 `ln_root_new` 创建 root，释放时调用 `ln_root_free`。

Handle

用户自定义数据统一使用 `LN_TYPE_HANDLE`。脚本只能保存和回传 handle，不能读取 payload。

Registry

registry 保存宿主长期引用，不是脚本可访问的整数表。跨调用保存值时优先使用 registry 或 root。

错误和资源控制

const ln_error *error = ln_vm_last_error(vm);

/* error->status
 * error->code
 * error->line / error->column
 * error->module / error->message
 */

/* LN_STATUS_BUDGET    可 ln_vm_resume
 * LN_STATUS_LIMIT     资源达到上限
 * LN_STATUS_FATAL     只能读取错误并 free VM
 */

错误文本是 VM 的短生命周期快照。资源紧张设备可以使用静态 arena，并限制内存、value stack、源码长度、调用深度、handle 和模块数量。

参考资料

完整 API 文档

仓库文档：`lnscript-public-api.md`，按头文件列出公开类型、函数和生命周期规则。

字节码规范

仓库文档：`lns-bytecode-format.md`，定义 LNSC 容器、段表、指令和校验流程。