システム

system モジュールは、ランタイム、メモリ、プロセス、ホスト、スーパーバイザー、およびクラスターの状態を報告します。また、選択されたランタイム制御も公開します。

このページは API リファレンスです。ほとんどのスニペットは独立した操作を示します。シャットダウン、ランタイム調整、分散ロックなどの制御には、明示的なポリシー認可とアプリケーション固有の失敗処理が必要です。

ロード

local system = require("system")

シャットダウン

終了コード付きでシステムシャットダウンをトリガー。ターミナルアプリに便利。実行中のアクターから呼び出すとシステム全体が終了:

local ok, err = system.exit(0)

戻り値: boolean, error

モジュールの一覧

メタデータ付きでロード済みのすべてのLuaモジュールを取得:

local mods, err = system.modules()

戻り値: table[], error

各モジュールテーブルの内容:

デプロイメントソース

system.sourceサブテーブルは、正規化されたデプロイメントのベースラインを読み取ります。これは、レジストリの履歴が適用される前の、アプリケーションが組み立てられたソース群から生成されたエントリ集合です。

local loaded, err = system.source.load()

戻り値: table, error

ownersはアプリケーションオーナーを先頭に、残りのオーナーをアルファベット順に並べてソートされます。アプリケーションオーナーは文字列"application"です。

local loaded, err = system.source.load()
if err then return nil, err end

for _, owner in ipairs(loaded.owners) do
    print(owner)
end

for _, entry in ipairs(loaded.entries) do
    print(entry.id, entry.kind)
end

ロードは1つの安定したソース世代から取得されるため、エントリとオーナーは常に同じベースラインを表します。各ソースの背後にあるファイルシステムのパスはランタイム内部のものであり、公開されません。ロードに失敗した場合は、背後のパスを漏らさず汎用の内部エラーを報告します。

権限: sourcesに対するsystem.read

メモリ統計

詳細なメモリ統計を取得:

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の値はヒープが2倍になると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値を取得または設定:

-- Get current value
local current, err = system.runtime.max_procs()

-- Set new value
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

プロセスホスト

ワーカーとキューの統計情報とともにすべてのプロセスホストを一覧:

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 はクラスタリングが提供する Raft バックエンドの KV ストアを必要とします。

すべての読み取り呼び出しはローカルかつ安価です: このノードのコミット済み状態のビューを報告し、ネットワークをブロックしません。

ノードアイデンティティ

system.node はクラスタ内のこのノード自身のアイデンティティを報告します。

local id, err = system.node.id()      -- this node's ID
local addr, err = system.node.addr()  -- advertised network address
local role, err = system.node.role()  -- "leader" | "voter" | "standby" | "non-member"

権限: node に対する system.read。

クラスタメンバーシップ

system.cluster はクラスタ全体のビューを報告します: メンバーと誰がリーダーかを報告します。

local members, err = system.cluster.members()  -- array of node tables
local leader, err = system.cluster.leader()    -- leader node ID, or "" if unknown
local n, err = system.cluster.size()           -- count of visible members

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: voter or standby
local role, err = system.raft.role()             -- same values as system.node.role()
local term, err = system.raft.term()             -- current Raft term
local idx, err = system.raft.commit_index()      -- highest committed log index
local stats, err = system.raft.stats()           -- raw stats map (string -> string)

権限: raft に対する system.read。ただし system.raft.stats() は raft_stats に対する system.read が必要。

分散ロック

system.lock はクラスタ全体の排他制御を提供します。ロックは呼び出しプロセスが所有するグローバルに一意な名前です。Raft レプリケートされたシステム KV ストア上に構築されているため、クラスタ全体で最大1つの保持者しか存在できません。保持者プロセスが終了またはそのノードが離脱するとロックは自動解放されます — スタックしたロックのクリーンアップは不要です。

local ok, err = system.lock.acquire("orders.migration")
if not ok then
  -- err has kind errors.ALREADY_EXISTS when another process holds the lock.
  -- Apply the caller's retry and backoff policy for that case if needed.
  return nil, err
end

-- critical section: only one holder cluster-wide
local released, release_err = system.lock.release("orders.migration")
if release_err then
  return nil, release_err
end
return released

取得はフェイルファスト: ロックが既に保持されている場合はブロックせず即座に false を返します。呼び出し側は独自のリトライとバックオフを実装します。現在の保持者のみが解放できます。保持していないロックを解放しても安全なno-opです。

権限: ロック name に対する system.lock（ポリシーで呼び出し元がロックできる名前を制限できる）。

権限

システム操作はセキュリティポリシー評価の対象。

エラー

エラーの処理についてはエラー処理を参照してください。