系统

查询运行时系统信息，包括内存使用、垃圾回收统计、CPU 详情和进程元数据。

加载

local system = require("system")

关闭

使用退出码触发系统关闭。适用于终端应用；从运行中的 actor 调用将终止整个系统：

local ok, err = system.exit(0)

返回: boolean, error

列出模块

获取所有已加载的 Lua 模块及其元数据：

local mods, err = system.modules()

返回: table[], error

每个模块表包含：

内存统计

获取详细的内存统计信息：

local stats, err = system.memory.stats()

返回: table, error

统计表包含：

当前分配

获取当前分配的字节数：

local bytes, err = system.memory.allocated()

返回: number, error

堆对象

获取已分配的堆对象数：

local count, err = system.memory.heap_objects()

返回: number, error

内存限制

设置内存限制（返回之前的值）：

local prev, err = system.memory.set_limit(1024 * 1024 * 100)

返回: number, error

获取当前内存限制：

local limit, err = system.memory.get_limit()

返回: number, error

强制 GC

强制执行垃圾回收：

local ok, err = system.gc.collect()

返回: boolean, error

GC 目标百分比

设置 GC 目标百分比（返回之前的值）。值为 100 表示堆翻倍时触发 GC：

local prev, err = system.gc.set_percent(200)

返回: number, error

获取当前 GC 目标百分比：

local percent, err = system.gc.get_percent()

返回: number, error

Goroutine 数量

获取活跃的 goroutine 数量：

local count, err = system.runtime.goroutines()

返回: number, error

GOMAXPROCS

获取或设置 GOMAXPROCS 值：

-- 获取当前值
local current, err = system.runtime.max_procs()

-- 设置新值
local prev, err = system.runtime.max_procs(4)

返回: number, error

CPU 数量

获取逻辑 CPU 数量：

local cpus, err = system.runtime.cpu_count()

返回: number, error

进程 ID

获取当前进程 ID：

local pid, err = system.process.pid()

返回: number, error

主机名

获取系统主机名：

local hostname, err = system.process.hostname()

返回: string, error

工作目录

获取运行时的当前工作目录：

local dir, err = system.process.cwd()

返回: string, error

进程主机

列出所有进程主机及其 worker 和队列统计信息：

local hosts, err = system.hosts.list()

返回: table[], error

每个主机表包含：

列出特定主机上运行的进程：

local procs, err = system.hosts.processes("app:host")

返回: table[], error

每个进程表包含：

服务状态

获取特定受监督服务的状态：

local state, err = system.supervisor.state("namespace:service")

返回: table, error

状态表包含：

所有服务状态

获取所有受监督服务的状态：

local states, err = system.supervisor.states()

返回: table[], error

每个状态表的格式与 system.supervisor.state() 相同。

集群原语

system.node、system.cluster、system.raft 和 system.lock 子表暴露集群层。启用集群时最为有用；在独立节点上会优雅降级——system.raft.* 报告"raft not available"，system.cluster 仅报告本地节点，system.lock 需要集群提供的全局注册表。

所有读取调用都是本地且廉价的：报告此节点已提交状态的视图，从不阻塞网络。

节点标识

system.node 报告此节点在集群中的自身标识。

local id, err = system.node.id()      -- 此节点的 ID
local addr, err = system.node.addr()  -- 广播的网络地址
local role, err = system.node.role()  -- "leader" | "voter" | "standby" | "non-member"

权限: node 上的 system.read。

集群成员资格

system.cluster 报告集群范围的视图：成员组成和谁是 leader。

local members, err = system.cluster.members()  -- 节点表数组
local leader, err = system.cluster.leader()    -- leader 节点 ID，未知时为 ""
local n, err = system.cluster.size()           -- 可见成员数量

system.cluster.members() 返回节点表数组。本地节点包含一次并排在最前。

权限: cluster 上的 system.read。

Raft 状态

system.raft 读取此节点本地对 Raft 共识核心的视图。Raft 未在此节点运行时所有函数返回 nil, error（"raft not available"）。

local leader, err = system.raft.is_leader()      -- boolean
local member, err = system.raft.is_member()      -- boolean：选民或备用
local role, err = system.raft.role()             -- 与 system.node.role() 相同的值
local term, err = system.raft.term()             -- 当前 Raft 任期
local idx, err = system.raft.commit_index()      -- 最高已提交日志索引
local stats, err = system.raft.stats()           -- 原始统计映射（string -> string）

权限: raft 上的 system.read，system.raft.stats() 需要 raft_stats 上的 system.read。

分布式锁

system.lock 提供集群范围的互斥锁。锁是调用进程拥有的全局唯一名称。基于 Strong 名称作用域构建，因此整个集群最多只能有一个持有者，且持有者进程退出或其节点离开时锁自动释放——不会产生卡死的锁需要清理。

local ok, err = system.lock.acquire("orders.migration")
if ok then
  -- 临界区：集群范围内只有一个持有者
  system.lock.release("orders.migration")
end

获取是非阻塞的：如果锁已被持有则立即返回 false，调用者自行实现重试和退避。只有当前持有者才能释放；释放未持有的锁是安全的空操作。

权限: 锁 name 上的 system.lock（策略可限制调用方可锁定的名称）。

权限

系统操作受安全策略评估约束。

错误

错误处理参见错误处理。