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.

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 optional deadline
local ok, err = process.cancel(destination, "5s")

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()  -- any: payload data

Synchronous Call

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

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

Permissions: process.call 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(source, ...)

-- 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"

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

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 and lookup processes by name:

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

Permissions: process.registry.register, process.registry.unregister on name

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

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