Process Management

Spawn, monitor, and communicate with child processes. Implements actor-model patterns with message passing, supervision, and lifecycle management.

The process global is always available — it does not require require() and does not need to be listed in modules:.

Process Information

Get the current frame ID or process ID:

local frame_id = process.id()  -- Call chain identifier
local pid = process.pid()       -- Process ID

Sending Messages

Send message(s) to a process by PID or registered name:

local ok, err = process.send(destination, topic, ...)

Permission: process.send on target PID

Spawning Processes

-- Basic spawn
local pid, err = process.spawn(id, host, ...)

-- With monitoring (receive EXIT events)
local pid, err = process.spawn_monitored(id, host, ...)

-- With linking (receive LINK_DOWN on abnormal exit)
local pid, err = process.spawn_linked(id, host, ...)

-- Both linked and monitored
local pid, err = process.spawn_linked_monitored(id, host, ...)

Permissions:

• process.spawn on process id
• process.host on host id
• process.spawn.monitored on process id (for monitored variants)
• process.spawn.linked on process id (for linked variants)

Process Control

-- Forcefully terminate a process
local ok, err = process.terminate(destination)

-- Request graceful cancellation with an optional reason
local ok, err = process.cancel(destination, "shutting down")

Permissions: process.terminate, process.cancel on target PID

Monitoring and Linking

Monitor or link to an existing process:

-- Monitoring: receive EXIT events when target exits
local ok, err = process.monitor(destination)
local ok, err = process.unmonitor(destination)

-- Linking: bidirectional, receive LINK_DOWN on abnormal exit
local ok, err = process.link(destination)
local ok, err = process.unlink(destination)

Permissions: process.monitor, process.unmonitor, process.link, process.unlink on target PID

Process Options

local options = process.get_options()
local ok, err = process.set_options({trap_links = true})

Inbox and Events

Get channels for receiving messages and lifecycle events:

local inbox = process.inbox()    -- Message objects from @inbox topic
local events = process.events()  -- Lifecycle events from @events topic

Event Types

Event Fields

Topic Subscription

Subscribe to custom topics:

local ch = process.listen(topic, options)
process.unlisten(ch)

Message Objects

When receiving from inbox or with {message = true}:

local msg = inbox:receive()

msg:topic()            -- string: topic name
msg:from()             -- string|nil: sender PID
msg:payload()          -- Payload: wrapper (call :data() to extract)
msg:payload():data()   -- any: actual payload value

Synchronous Call

Spawn a process, wait for its result, and return:

local result, err = process.exec(id, host, ...)

Permissions: process.exec on process id, process.host on host id

Process Upgrade

Upgrade the current process to a new definition while preserving PID:

-- Upgrade to new version, passing state
process.upgrade(id, ...)

-- Keep same definition, re-run with new state
process.upgrade(nil, preserved_state)

Context Spawner

Create a spawner with custom context for child processes:

local spawner = process.with_context({request_id = "123"})

Permission: process.context on "context"

Spawner with Options

process.with_options(options) creates a spawner that carries spawn-time options (e.g., a network selector) instead of context values:

local spawner = process.with_options({network = "app:tor_proxy"})

Permission: process.context on "context"; selecting a network additionally requires network.select on that network ID.

SpawnBuilder Methods

SpawnBuilder is immutable - each method returns a new instance:

spawner:with_context(values)      -- Add context values
spawner:with_actor(actor)         -- Set security actor
spawner:with_scope(scope)         -- Set security scope
spawner:with_name(name)           -- Set process name
spawner:with_message(topic, ...)  -- Queue message to send after spawn
spawner:with_options(options)     -- Merge spawn-time options (e.g. network)

Permission: process.security on "security" for :with_actor() and :with_scope()

Spawner Spawn Methods

spawner:spawn(id, host, ...)
spawner:spawn_monitored(id, host, ...)
spawner:spawn_linked(id, host, ...)
spawner:spawn_linked_monitored(id, host, ...)

Same permissions as module-level spawn functions.

Name Registry

Register a process under a name and reach it by that name instead of its PID. Any function that takes a destination (send, terminate, cancel, monitor, link, ...) accepts a registered name in place of a PID.

local ok, err = process.registry.register(name)               -- self, local scope
local pid, err = process.registry.lookup(name)
local ok, err = process.registry.unregister(name)

Scope

The optional scope argument selects the consistency guarantee of the name. It defaults to LOCAL. The four scopes and their guarantees are described in the Cluster Guide; in short:

On a standalone node only LOCAL is meaningful; the cluster scopes require clustering.

register

local ok, err = process.registry.register(name, pid, scope)

Returns true on success, or nil, error on failure. Conflicts (name already registered to a different PID under a cluster scope) return errors.ALREADY_EXISTS. Registering the same name to the same PID is idempotent. A STRONG registration blocks until every live node acknowledges or the reservation deadline expires; on timeout it returns an error.

Registering on behalf of a different PID additionally requires the process.registry.foreign permission on the target PID.

lookup

local pid, err = process.registry.lookup(name)

Returns the registered PID string, or nil, error with kind errors.NOT_FOUND when the name is not registered.

unregister

local ok, err = process.registry.unregister(name, scope)

scope defaults to LOCAL and must match the scope the name was registered under. For CONSISTENT and STRONG, the owning process is the one allowed to unregister; unregistering a name owned by another PID returns false. Names also release automatically when the owning process exits (and, for cluster scopes, when its node leaves), so explicit unregister is for early release.

Permissions

Permissions control what a calling process can do. All checks use the caller's security context (actor) against the target resource.

Policy Evaluation

Policies can allow/deny based on:

• Actor: The security principal making the request
• Action: The operation being performed (e.g., process.send)
• Resource: The target (PID, process id, host id, or name)
• Attributes: Additional context including pid (caller's process ID)

Permission Reference

Cluster name scopes are authorized by scope-suffixed variants of these actions (process.registry.register.eventual, .consistent, .strong, and the matching unregister actions), so a policy can grant local naming separately from cluster-wide naming.

Multiple Permissions

Some operations require multiple permissions:

Errors

See Error Handling for working with errors.

See Also

• Channels - Inter-process communication
• Message Queue - Queue-based messaging
• Functions - Function invocation
• Supervision - Process lifecycle management
• Cluster - Name scopes and cluster-wide naming